Building your first Agent Protocol-compliant agent in 15 minutes

What you'll build

A tiny agent service that speaks the Agent Protocol: clients create a task, trigger steps, and read back artifacts. The internal logic is deliberately trivial so the focus stays on the protocol surface.

Step 1 — Model the core resources

Agent Protocol centres on a small set of resources. A task represents a goal; a step is one unit of the agent's execution; an artifact is an output produced along the way.

Task     { task_id, input, artifacts[] }
Step     { step_id, task_id, output, is_last }
Artifact { artifact_id, file_name }

Step 2 — Create a task

Expose an endpoint that accepts an input goal and returns a new task with an identifier.

POST /ap/v1/agent/tasks
Content-Type: application/json

{ "input": "List three risks in the attached plan." }

# → 200 OK
{ "task_id": "t_01", "input": "List three risks...", "artifacts": [] }

Step 3 — Execute a step

Each call to the steps endpoint advances the agent. Return the step's output and whether it's the final step. Real agents may plan, call tools (for example over MCP), and iterate here.

POST /ap/v1/agent/tasks/t_01/steps
Content-Type: application/json

{ "input": "" }

# → 200 OK
{ "step_id": "s_01", "task_id": "t_01", "output": "Risk 1: ...", "is_last": true }

Step 4 — Return artifacts

If your agent produces files or structured outputs, expose them as artifacts clients can list and download.

GET /ap/v1/agent/tasks/t_01/artifacts

# → 200 OK
{ "artifacts": [ { "artifact_id": "a_01", "file_name": "risks.md" } ] }

Step 5 — Call it from a client

Because the interface is standard, any Agent Protocol client can drive your agent without knowing its internals: create a task, loop over steps until is_last, then fetch artifacts.