AgentProtocol.ai
Protocol selectorCompare protocols
//reference

AI agent API

An AI agent API is the HTTP interface a client uses to start an agent, monitor its progress and collect results. This guide covers common API patterns, how they relate to protocols, and when a standard beats a custom design.

Layer: client ↔ agent

What is an AI agent API?

An AI agent API is how software talks to an agent from the outside. Instead of a single request/response, an agent API typically models long-running work: you submit a goal, the agent works over multiple steps, and you retrieve progress and outputs as they appear.

An API is one system's specific interface. A protocol is a shared convention many systems implement. The two meet in specs like the Agent Protocol, which defines an agent API as a standard so different agents expose the same shape.

Common agent API patterns

  • Runs / tasks — create a unit of work with an input goal; get back an identifier.
  • Steps — the agent executes incrementally; clients can list or stream steps.
  • Artifacts — files or structured outputs the agent produces during a run.
  • Status & polling / streaming — check whether work is queued, running, done or failed, via polling or server-sent events.
agent-api.http
http
# 1. Start a task
POST /ap/v1/agent/tasks
{ "input": "Draft a launch checklist for our new API." }

# 2. Execute a step
POST /ap/v1/agent/tasks/{task_id}/steps
{ "input": "" }

# 3. Fetch produced artifacts
GET /ap/v1/agent/tasks/{task_id}/artifacts

Custom API vs a standard

A bespoke API can be the fastest path for a closed, single-consumer system. A standard like Agent Protocol pays off when you want interchangeable clients, third-party integrations, or to avoid re-teaching every consumer a new interface.

Consideration
Custom API
Agent Protocol (standard)
Time to first version✓Yes~Partial
Interchangeable clients✕No✓Yes
Third-party tooling~Partial✓Yes
Full control of shape✓Yes~Partial
You can do both
A pragmatic pattern: expose a standard Agent Protocol surface for interoperability, and add custom endpoints for the few needs the standard doesn't cover.

How agent APIs relate to MCP and A2A

The agent API is the client-to-agent layer. Behind it, the agent may use MCP to reach tools and A2A to delegate to peers. See the full comparison for how the layers stack.

//questions

Frequently asked questions

What is the difference between an AI agent API and a protocol?

An API is a specific system's interface. A protocol is a shared convention many systems adopt so their interfaces match. The Agent Protocol spec is a protocol that defines an agent API, so multiple agents can present the same API shape.

Why do agent APIs use runs, tasks and steps?

Because agent work is usually long-running and multi-step. Modelling runs, steps and artifacts lets a client start work, watch it progress, and collect outputs — rather than waiting on one blocking call.

Should I build a custom agent API or adopt a standard?

Build custom when you control both ends and need speed or full control. Adopt a standard like Agent Protocol when you want interchangeable clients, third-party integrations or long-term interoperability. Combining the two is common.

// AgentProtocol is independent and not the official source for any protocol named here.