Agents API

Document ID: API-003
File Path: docs/09-api/agents.md
Version: 1.0.0
Status: Draft
Owner: AI Platform Team
Last Updated: 2026-06-27

1. Purpose

This document defines the REST/gRPC API for managing agents — their definitions, versions, and runs. It is the control-plane interface to the Agent Runtime and the Agent Definition model.

All endpoints inherit the API conventions and require authentication.

2. Resources

Resource	Description
`agent`	A versioned agent definition
`agent_version`	An immutable published version of an agent
`run`	A single execution of an agent against a goal
`session`	A multi-run conversational context

3. Endpoints

Method	Path	Scope
POST	`/api/v1/agents`	`agents:write`
GET	`/api/v1/agents`	`agents:read`
GET	`/api/v1/agents/{id}`	`agents:read`
PATCH	`/api/v1/agents/{id}`	`agents:write`
DELETE	`/api/v1/agents/{id}`	`agents:write`
POST	`/api/v1/agents/{id}:publish`	`agents:write`
GET	`/api/v1/agents/{id}/versions`	`agents:read`
POST	`/api/v1/agents/{id}:run`	`agents:run`
GET	`/api/v1/runs/{id}`	`agents:read`
GET	`/api/v1/runs/{id}/stream`	`agents:read`
POST	`/api/v1/runs/{id}:cancel`	`agents:run`
POST	`/api/v1/sessions`	`agents:run`

4. Agent Definition

{
  "id": "agt_01H...",
  "object": "agent",
  "name": "order-assistant",
  "description": "Handles customer order questions",
  "model_selector": { "capability": "chat", "class": "balanced" },
  "instructions": "You are a helpful order assistant.",
  "tools": ["http.request", "lookup_order"],
  "memory": { "scopes": ["project", "organization"], "enabled": true },
  "policies": ["pii-guard"],
  "version": 3,
  "status": "published"
}

Fields map to the Agent Definition spec: model_selector resolves via the LLM Gateway; tools reference the Tools API; memory configures Memory Engine access; policies are enforced by the Policy Engine.

5. Running an Agent

POST /api/v1/agents/agt_01H...:run
Idempotency-Key: run-order-123

{
  "input": { "message": "Where is order 123?" },
  "session_id": "ses_01H...",
  "stream": true,
  "budget": { "max_cost_usd": 0.25 },
  "context": { "correlation_id": "trace_01H..." }
}

Response (non-streaming):

{
  "run_id": "run_01H...",
  "status": "succeeded",
  "output": { "message": "Order 123 shipped yesterday." },
  "steps": 4,
  "usage": { "total_tokens": 1820, "cost_usd": 0.021, "tool_calls": 2 }
}

budget is enforced via LLM Gateway token management.

6. Run Lifecycle & Streaming

queued → planning → executing → (succeeded | failed | cancelled)

GET /api/v1/runs/{id}/stream (SSE) emits the agent’s progress: planner steps, tool invocations, model deltas, and memory reads — a superset aligned with the Agent Runtime Protocol and the LLM Gateway streaming events.

7. Sessions

A session preserves conversational context across runs:

{ "id": "ses_01H...", "agent": "agt_01H...", "turns": 6, "memory_scope": "session" }

Runs referencing a session_id share working/conversation memory and (optionally) sticky model routing (see Routing §8).

8. Versioning & Publishing

Editing an agent creates a draft; :publish produces an immutable agent_version.
In-flight runs continue on the version they started with.
A run may pin version; otherwise the active published version is used.

9. Events

Mutations emit agent.created, agent.published, agent.run.started, agent.run.completed, agent.run.failed to the Event Bus; webhooks mirror these.

10. Errors

Uses the standard error envelope. Notable codes: model_not_found (selector unsatisfiable), budget_exceeded, tool_not_found, forbidden (policy denied).

11. Dependencies

13. Revision History

Version	Date	Description
1.0.0	2026-06-27	Initial Agents API specification