ANIP — Agent-Native Interface Protocol

REST APIs are simple. ANIP gives agents confidence.

The value is not "agents can call APIs better." The value is "agents can reason before acting."

anip.dev | Docs | Install | Blog | Discord | Spec | Contribute

Why "ANIP"?

Agent-Native Interface Protocol. Two words do different work:

• Interface — the surface agents interact with. What capabilities exist, what they cost, what authority they require, what they do. ANIP defines the shape of that surface.
• Protocol — the rules both parties agree to follow. How discovery works, how delegation chains are validated, how failures are structured. ANIP standardizes those rules.

This follows a well-established naming pattern in networked systems: HTTP (HyperText Transfer Protocol), SMTP (Simple Mail Transfer Protocol), IP (Internet Protocol). In each case, "protocol" describes the standardized rules, while the preceding words describe what flows through them. ANIP is no different — it's the protocol for agent-native interfaces.

The Shift

Every major interface paradigm emerged when the dominant consumer changed:

Each shift wasn't a new format — it was a new set of assumptions about who is on the other end. That shift is happening again. The primary consumer of digital services is becoming an AI agent.

The Problem

Today's interfaces were designed for humans. When agents interact with them, they do it in one of two ways — both wrong:

Computer-use agents (OpenClaw, Anthropic Computer Use, Operator) teach AI to operate a mouse and keyboard against GUIs built for human eyes. Brilliant engineering. Fundamentally a workaround.

REST APIs assume a human developer reads docs, writes deterministic code, and ships a program. When an agent uses an API directly, it discovers auth requirements by getting a 401, learns permissions by getting a 403, finds out costs after being charged, and can't undo what it doesn't know is irreversible.

MCP (Model Context Protocol) improves discovery and standardizes tool access, but it still does not make execution boundaries first-class. Authority, scope, side effects, reversibility, cost, and failure posture are not protocol-level primitives. An agent may still complete the task, but it is doing so without the system defining upfront what it is allowed to do, what risks it is taking, and whether a mistaken call can be rolled back at all.

What It Looks Like

Without ANIP — what agents deal with today:

Agent wants to book a flight
→ Reads OpenAPI spec (designed for human developers)
→ Guesses that POST /bookings is the right endpoint
→ Discovers auth requirements by getting a 401
→ Discovers insufficient permissions by getting a 403
→ Books the flight
→ Discovers the charge was $800 not $420 (undeclared currency conversion)
→ Cannot undo (no rollback information was available)
→ Audit log exists but agent didn't know to check it

With ANIP:

Agent queries manifest → profile handshake
→ Sees book_flight: irreversible, financial, cost: ~$420±10%
→ Checks delegation chain has travel.book scope + constraints.budget {USD, $500}
→ Confirms rollback_window: none (knows upfront it's permanent)
→ Confirms observability: logged, 90-day retention
→ Decides to proceed, executes with full context

sequenceDiagram
    participant Agent
    participant ANIP as ANIP Service

    Agent->>ANIP: GET /.well-known/anip
    ANIP-->>Agent: discovery (capabilities, endpoints)

    Agent->>ANIP: GET /anip/manifest
    ANIP-->>Agent: full capability declarations

    Agent->>ANIP: POST /anip/tokens (+ API key)
    ANIP-->>Agent: signed JWT delegation token

    Agent->>ANIP: POST /anip/invoke/search_flights (+ token)
    ANIP-->>Agent: {success, result, cost_actual}

Every assumption that was implicit becomes explicit, typed, and queryable.

Five things an agent doesn't know with REST but does with ANIP:

1. This action is irreversible — side_effect: irreversible, rollback_window: none
2. This costs $280–500 — cost.financial: { range_min: 280, range_max: 500 }
3. Search before booking — requires: [{ capability: "search_flights" }]
4. Budget will be enforced — scope: ["travel.book"] with constraints.budget: { currency: "USD", max_amount: 500 } in the delegation chain
5. Who can fix a permission problem — resolution: { grantable_by: "human:[email protected]" }

That last one is the killer feature. When a budget-exceeded failure comes back, it doesn't just say "denied" — it tells the agent exactly who can increase the budget. The agent can autonomously escalate to the right person. That's a capability that doesn't exist in REST, MCP, or OpenAPI.

sequenceDiagram
    participant Agent
    participant ANIP as ANIP Service
    participant Human

    Agent->>ANIP: POST /anip/invoke/book_flight (+ token)
    ANIP-->>Agent: budget_exceeded (grantable_by: human)

    Agent->>Human: request_budget_increase ($380, UA205)
    Human-->>Agent: approved

    Human->>ANIP: POST /anip/tokens (higher constraints.budget)
    ANIP-->>Human: new signed JWT

    Human-->>Agent: new token

    Agent->>ANIP: POST /anip/invoke/book_flight (+ new token)
    ANIP-->>Agent: {success: true, booking: BK-0018}

See it in action. This is real output from an autonomous agent consuming the ANIP reference server. No scripting — the agent discovers its authority, searches flights, hits the budget wall, escalates, books, and verifies the audit trail, all from ANIP metadata.

ANIP Agent Mode | Server: http://127.0.0.1:9100 | Human delegation: simulated

SETUP: Fetching ANIP manifest and requesting tokens
Generated 5 tools from manifest: search_flights, book_flight,
  check_permissions, request_budget_increase, query_audit
Issued tokens:
  demo-b0995ff9: search_flights (travel.search)
  demo-f72e58e6: book_flight (travel.book, budget: {USD, $300})

AGENT LOOP

Agent: Let me start by checking my permissions and searching for flights.

[1/15] check_permissions → available=['search_flights']
[2/15] check_permissions → available=['book_flight']

Agent: I have search and book permissions. Budget is $300. Searching flights...

[3/15] search_flights(origin=SEA, destination=SFO, date=2026-03-10) → SUCCESS
  AA100 (nonstop) 08:00→10:15  $420  ← exceeds budget
  UA205 (nonstop) 11:30→13:45  $380  ← exceeds budget
  DL310 (1 stop)  14:00→18:30  $280  ← within budget

Agent: Nonstop flights exceed my $300 budget. Trying UA205 anyway...

[4/15] book_flight(UA205) → BLOCKED
  budget_exceeded: costs $380 but authority is max $300

Agent: Requesting budget increase for the nonstop flight.

[5/15] request_budget_increase(token=demo-f72e58e6, budget=$380,
         flight=UA205, date=2026-03-10)
  [Simulated human grants $380 for book_flight — UA205 on 2026-03-10]
  → approved, new token: demo-c5da6ccd

[6/15] book_flight(UA205, token=demo-c5da6ccd) → SUCCESS
  Booking confirmed: BK-0018

[7/15] query_audit(token=demo-c5da6ccd) → 2 audit entries

Agent: Done. UA205 nonstop SEA→SFO, March 10, $380. 7 tool calls.

The agent was never told the steps. It discovered its authority from check_permissions, learned prices from search_flights, hit the budget wall from ANIP's structured failure (not an HTTP 403), escalated through request_budget_increase with the exact failed flight/date, and verified its work through the audit trail. Every decision came from ANIP metadata. (Run it yourself)

When to Use ANIP

ANIP is the right interface when the consumer is an AI agent. The distinction isn't complexity — it's consumer.

• Consumer is a human developer writing deterministic code → REST/API is correct
• Consumer is an AI agent reasoning and acting autonomously → ANIP is correct

A simple read-only get_weather capability still benefits from ANIP when an agent consumes it: the agent knows it's safe to call repeatedly (side_effect: read), can discover it without reading docs, can verify its delegation scope before calling, and gets structured failures instead of HTTP codes.

ANIP scales down gracefully. A read-only service with no auth needs only the 5 core primitives and the ceremony is minimal. The value is in the consistency: agents that speak ANIP can interact with any ANIP service without reading documentation, regardless of complexity.

HTTP isn't overkill for serving a single static HTML file. The protocol is the same — GET, 200, content. The simplicity of the content doesn't make the protocol unnecessary. What makes HTTP unnecessary is when you're not on the web at all. Same with ANIP — what makes it unnecessary is when there's no agent in the picture.

Why Implement ANIP First

An ANIP manifest is not just a description of a service — it is enough to derive the service's tool surface for an agent. An agent runner can fetch the manifest, generate tool definitions programmatically (with side effects, costs, prerequisites, and scope requirements embedded in each tool description), and hand them to the model. No per-service hand-wiring. No hand-authored tool descriptions. The demo agent proves this: generate_tools(manifest) produces the agent's entire actionable interface from live ANIP metadata.

And there's a second adoption argument we didn't expect: implement ANIP once and you get every surface for free.

ANIP ships with library packages for REST/OpenAPI, GraphQL, and MCP that mount directly on your service — one ANIPService, multiple interfaces, zero proxying.

                                ┌─→ REST/OpenAPI (auto-generated spec + Swagger UI)
                                │
ANIP service ──→ mount packages ┼─→ GraphQL (auto-generated schema + directives)
                                │
                                └─→ MCP (auto-generated tools for Claude, Cursor, etc.)

await mountAnip(app, service);           // ANIP protocol routes
await mountAnipRest(app, service);       // REST at /api/*
await mountAnipGraphQL(app, service);    // GraphQL at /graphql
await mountAnipMcpHono(app, service);    // MCP Streamable HTTP at /mcp

This inverts the usual calculus. The conventional path — build a REST API, then layer MCP on top for agents — gives you two surfaces that each need maintenance and neither speaks the agent's language natively. ANIP gives you the native agent interface and REST, GraphQL, and MCP as byproducts. You're actually better off implementing ANIP than building REST first.

Standard REST and GraphQL clients work normally — they ignore the ANIP metadata (x-anip-* OpenAPI extensions, @anip* GraphQL directives). ANIP-aware agents use the metadata for delegation, cost awareness, and side-effect reasoning. Graceful degradation by design.

One honest caveat. The REST and GraphQL packages translate the protocol surface but lose visibility into the delegation chain, cost signaling, and capability graph. For read and write capabilities, that's fine. For irreversible financial operations, native ANIP is strongly recommended — purpose-bound authority and multi-hop delegation don't survive the translation.

Transport Bindings

ANIP is transport-agnostic. The protocol semantics — delegation, scope, side effects, cost, audit — stay the same regardless of transport. The same service can be consumed over any binding.

              ┌─→ HTTP    (default — REST-style JSON, all 5 runtimes)
              │
ANIP service ─┼─→ stdio   (JSON-RPC 2.0 on stdin/stdout — local agents)
              │
              └─→ gRPC    (shared proto contract — internal platforms, service mesh)

• HTTP is the default. All 5 runtimes, all framework adapters (FastAPI, Hono, Express, Spring Boot, Quarkus, ASP.NET Core, net/http, Gin).
• stdio is for local agents. An agent spawns the service as a subprocess and talks the full ANIP protocol over stdin/stdout. No network, no port. All 5 runtimes.
• gRPC is for internal platforms. A shared protobuf service definition defines the wire contract. Strongly typed, efficient, works with service mesh and mTLS. Python + Go currently, other runtimes from the same proto.

An agent that speaks ANIP can discover, delegate, invoke, and audit over any of these transports.

Core Principles

ANIP defines 9 primitives in two tiers:

Core (ANIP-compliant) — every implementation MUST support:

1. Capability Declaration — intent-based ("I can book flights"), not endpoint-based (POST /bookings)
2. Side-effect Typing — read, write, irreversible, transactional — with rollback windows
3. Delegation Chain — structured identity as a DAG: who's asking, on whose behalf, with what scoped authority
4. Permission Discovery — query what you're allowed to do before attempting it
5. Failure Semantics — errors that reference the delegation chain, budget, and scope — not HTTP status codes

Contextual (ANIP-complete) — standardized shape, SHOULD support:

1. Cost & Resource Signaling — bidirectional: service declares cost, agent declares budget, service offers alternatives
2. Capability Graph — capabilities know their prerequisites and what they compose with, so agents can navigate without reading docs
3. State & Session Semantics — stateless vs. continuation vs. multi-step workflow, explicitly declared
4. Observability Contract — what's logged, how long it's retained, who can audit it

Quick Start

ANIP ships a service runtime that handles all protocol plumbing — delegation, audit, signing, checkpoints — so you only write business logic.

Python (anip-service + anip-fastapi):

from anip_service import ANIPService, Capability
from anip_fastapi import mount_anip
from fastapi import FastAPI

service = ANIPService(
    service_id="my-service",
    capabilities=[search_flights, book_flight],
    storage="sqlite:///anip.db",
    trust="signed",
    authenticate=lambda bearer: API_KEYS.get(bearer),
)

app = FastAPI()
mount_anip(app, service)

TypeScript (@anip-dev/service + @anip-dev/hono):

import { createANIPService } from "@anip-dev/service";
import { mountAnip } from "@anip-dev/hono";
import { Hono } from "hono";

const service = createANIPService({
  serviceId: "my-service",
  capabilities: [searchFlights, bookFlight],
  storage: { type: "sqlite", path: "anip.db" },
  trust: "signed",
  authenticate: (bearer) => API_KEYS[bearer] ?? null,
});

const app = new Hono();
const { shutdown, stop } = mountAnip(app, service);

Capabilities are plain functions — declare what they do, handle the request, return data:

from anip_service import Capability
from anip_core import CapabilityDeclaration, CapabilityInput, CapabilityOutput, SideEffect, SideEffectType

search_flights = Capability(
    declaration=CapabilityDeclaration(
        name="search_flights",
        description="Search available flights",
        contract_version="1.0",
        inputs=[CapabilityInput(name="origin", type="airport_code", description="Departure airport")],
        output=CapabilityOutput(type="flight_list", fields=["flight_number", "price"]),
        side_effect=SideEffect(type=SideEffectType.READ, rollback_window="not_applicable"),
        minimum_scope=["travel.search"],
    ),
    handler=lambda ctx, params: {"flights": do_search(params["origin"], params["destination"], params["date"])},
)

The runtime handles discovery, JWT tokens, signed manifests, delegation validation, audit logging, and Merkle checkpoints. See the Python example, TypeScript example, Go example, Java example, and C# example for complete working services.

For advanced use cases that need direct access to the SDK primitives (KeyManager, DelegationEngine, AuditLog, MerkleTree), the underlying packages (anip-core/anip-crypto/anip-server and @anip-dev/core/@anip-dev/crypto/@anip-dev/server) remain available.

Install

ANIP Studio runs as a full design/review/publishing product via Docker Compose, with a read-only showcase mode for public demos. Conformance suite and contract testing are available in-repo. Full package lists and details are in docs/distribution.md.

Status

ANIP is under active development. The spec is at v0.24 with input resolution metadata — building on v0.23's capability composition and approval grants, v0.22's canonical parent_token semantics and delegated capability-targeted issuance, v0.21's cross-service contracts and structured recovery targets, v0.20's bootstrap auth hardening and capability-targeted root issuance, and earlier foundations through v0.19. Multi-agent coordination and federated trust remain open. See SPEC.md § Roadmap for the full breakdown.

v0.24 ships input resolution metadata. Capability inputs declare a resolution block (mode + resolver_ref + on_missing/on_ambiguous/on_unresolved) so runtimes, generators, and agents have a portable contract for whether an input is closed-enum, backend-resolved, app-selected, actor-policy-derived, explicit-only, or clarify-on-miss. Adjacent typed hints (semantic_type, entity_reference, allowed_values, catalog_ref, input_meanings) give the resolution block its substrate. Pure additive — v0.23 manifests parse unchanged. Building on v0.23's capability composition + approval grants, v0.22's delegated issuance, v0.21's cross_service_contract / recovery_target, v0.20's bootstrap auth, and all features through v0.19.

This is a community effort. We'd rather define this standard thoughtfully and in the open than let it emerge ad-hoc.

What exists today:

• Manifesto — why this moment matters
• Spec — the technical design (v0.24)
• Guide — walkthrough of the reference implementation with design rationale
• Reference implementation — Python — anip-service + FastAPI, ~150 lines of business logic
• Reference implementation — TypeScript — @anip-dev/service + Hono, same capabilities and endpoints
• Reference implementation — Go — anip-service + net/http, same capabilities and endpoints
• Reference implementation — Java (Spring Boot) — anip-service + Spring Boot, same capabilities and endpoints
• Reference implementation — Java (Quarkus) — anip-service + Quarkus, same capabilities and endpoints
• Reference implementation — C# — Anip.Service + ASP.NET Core, same capabilities and endpoints
• Python SDK packages: anip-core, anip-crypto, anip-server, anip-service, anip-fastapi, anip-rest, anip-graphql, anip-mcp, anip-stdio, anip-grpc, anip-studio
• TypeScript SDK packages: @anip-dev/core, @anip-dev/crypto, @anip-dev/server, @anip-dev/service, @anip-dev/hono, @anip-dev/express, @anip-dev/fastify, @anip-dev/mcp, @anip-dev/mcp-hono, @anip-dev/mcp-express, @anip-dev/mcp-fastify, @anip-dev/rest, @anip-dev/graphql, @anip-dev/stdio
• Go SDK packages: core, crypto, server, service, httpapi, ginapi, restapi, graphqlapi, mcpapi, stdioapi, grpcapi
• Java SDK packages: anip-core, anip-crypto, anip-server, anip-service, anip-spring-boot, anip-quarkus, anip-rest (shared), anip-rest-spring, anip-rest-quarkus, anip-graphql (shared), anip-graphql-spring, anip-graphql-quarkus, anip-mcp (shared), anip-mcp-spring, anip-mcp-quarkus, anip-stdio
• C# SDK packages: Anip.Core, Anip.Crypto, Anip.Server, Anip.Service, Anip.AspNetCore, Anip.Rest, Anip.Rest.AspNetCore, Anip.GraphQL, Anip.GraphQL.AspNetCore, Anip.Mcp, Anip.Mcp.AspNetCore, Anip.Stdio
• Transport bindings:
• HTTP: default transport, all 5 runtimes, all framework adapters
• stdio: native ANIP-over-stdio via JSON-RPC 2.0 on stdin/stdout — all 5 runtimes
• gRPC: native ANIP-over-gRPC via shared proto/anip/v1/anip.proto — Python + Go (Java, C#, TypeScript later)
• Interface packages — mount alongside ANIP on the same service:
• MCP: @anip-dev/mcp / anip-mcp (shared), framework adapters for Streamable HTTP
• REST: @anip-dev/rest / anip-rest (shared, auto-generated OpenAPI + Swagger UI)
• GraphQL: @anip-dev/graphql / anip-graphql (shared, auto-generated SDL + directives)
• ANIP Studio — product/design workbench for PM and developer review, package/template publishing, generated-service validation, read-only showcase browsing, and service inspection
• Conformance suite — language-agnostic HTTP-based protocol compliance tests
• Contract testing — side-effect contract verification (read purity, event classification, cost presence, compensation workflows)
• Showcase apps — flagship GTM Agent plus governed fronting showcases for Jira, Slack, GitHub, GitLab, Linear, Notion, and Superset, alongside earlier travel, finance, and DevOps examples
• Demo agent — an AI agent that consumes ANIP to reason before acting, handle budget failures, and verify audit trails
• JSON Schema — validate any ANIP implementation against the spec
• Security policy — vulnerability reporting, trust model summary, deployment guidance
• Trust model — deep dive on cryptographic architecture and anchored trust
• Agent contract drafter skill — machine-optimized guidance for drafting a local experimental ANIP service definition
• Deployment guide — horizontal scaling, PostgreSQL storage, and multi-replica production deployment
• Open questions — where we need input

Agent-facing guidance is itself an example of ANIP's philosophy applied to documentation. The current skills/anip-contract-drafter.md file gives coding agents a bounded way to draft a local experimental anip-service-definition.json, validate it with the CLI, and generate a first service. It is intentionally not a replacement for Studio review, Registry signing, package locks, or release evidence.

What's next:

• anip.dev — documentation hub, package ecosystem portal, Studio hosting at studio.anip.dev
• Federated trust — cross-service delegation chains and token exchange
• Studio streaming visualization — watch streaming invocations unfold in real-time (Phase 2.1)
• Studio lineage tracing — trace invocation chains through audit entries
• Streaming backpressure — flow control signaling between agents and services
• Posture-aware agent behavior — agents adapting interaction strategies based on service posture
• gRPC transport expansion — Java, C#, TypeScript bindings from the shared proto

If this resonates, star the repo, join the ANIP Discord, open an issue, or contribute. If you think we're wrong, tell us why — that's equally valuable.

How This Was Built

ANIP was designed through parallel sessions with AI coding and review agents: drafting protocol surfaces, stress-testing delegation and approval behavior, finding security bypasses, and validating generated implementations across languages. The public history is intentionally curated for release readability; the product itself remains a protocol for agent-native interfaces, co-created with agents and tested against agent-driven usage.

License

Specification documents (SPEC.md, MANIFESTO.md, GUIDE.md, skills/, docs/): CC-BY 4.0 Reference implementations and tooling (examples/, packages/, conformance/, schema/): Apache 2.0

Attribution

When implementing or referencing ANIP, please cite: "Agent-Native Interface Protocol (ANIP) — anip-protocol/anip"