Agents API¶

Prefix: /api/v1/agents

CRUD¶

Method	Path	Description
`POST`	`/`	Create agent. Returns 201. Returns 409 if name exists.
`GET`	`/`	List all agents.
`GET`	`/{name}`	Get agent spec.
`PUT`	`/{name}`	Update agent (partial).
`DELETE`	`/{name}`	Delete agent.

Create Agent¶

curl -X POST http://localhost:8000/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
    "description": "A helpful assistant",
    "system_prompt": "You are helpful.",
    "primitives": {
      "memory": {"enabled": true, "namespace": "agent:{agent_name}"}
    },
    "hooks": {"auto_memory": true, "auto_trace": false},
    "max_turns": 20
  }'

Chat¶

Method	Path	Description
`POST`	`/{name}/chat`	Non-streaming chat
`POST`	`/{name}/chat/stream`	SSE streaming chat (background task)

Non-Streaming Chat¶

curl -X POST http://localhost:8000/api/v1/agents/my-agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "session_id": "optional-session-id"}'

Response:

{
  "response": "Hello! How can I help you?",
  "session_id": "abc123",
  "agent_name": "my-agent",
  "turns_used": 1,
  "tools_called": [],
  "artifacts": [],
  "metadata": {"trace_id": "..."}
}

Streaming Chat¶

curl -N -X POST http://localhost:8000/api/v1/agents/my-agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "session_id": "my-session"}'

Returns text/event-stream. The run executes in a background task: if the client disconnects, the run completes and stores the conversation turn. See Streaming for event types.

Sessions¶

Each chat uses a session_id to track conversation history. Multiple sessions can exist per agent.

Method	Path	Description
`GET`	`/{name}/sessions`	List all sessions for this agent
`POST`	`/{name}/sessions/cleanup`	Delete old sessions, keeping most recent N
`GET`	`/{name}/sessions/{session_id}`	Get conversation history
`GET`	`/{name}/sessions/{session_id}/status`	Check if a background run is active (`"running"` or `"idle"`)
`GET`	`/{name}/sessions/{session_id}/stream`	SSE reconnect stream
`DELETE`	`/{name}/sessions/{session_id}/run`	Cancel active run
`DELETE`	`/{name}/sessions/{session_id}`	Delete session history

SSE Reconnect Stream¶

curl -N http://localhost:8000/api/v1/agents/my-agent/sessions/my-session/stream

Reconnects to a running or recently-completed session. Replays all stored events from the event store with token throttling for smooth playback, then polls for new events if the run is still active. Stays open for up to 3 minutes waiting for a resumed run. Returns text/event-stream.

Cancel Active Run¶

curl -X DELETE http://localhost:8000/api/v1/agents/my-agent/sessions/my-session/run

Cancels the background task for this session. The checkpoint is deleted, the event store status is set to "cancelled", and conversation history up to the cancellation point is preserved.

{"status": "cancelled", "session_id": "my-session"}

Returns 404 if no active run exists for the session.

List Sessions¶

curl http://localhost:8000/api/v1/agents/my-agent/sessions

Get Session History¶

curl http://localhost:8000/api/v1/agents/my-agent/sessions/my-session

{
  "agent_name": "my-agent",
  "session_id": "my-session",
  "messages": [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi! How can I help?"}
  ]
}

Check Background Run Status¶

curl http://localhost:8000/api/v1/agents/my-agent/sessions/my-session/status

{"status": "running"}

Returns "running" if a background task is actively processing this session, "idle" otherwise. The UI uses this to show a "working in the background" indicator and poll for completion.

Export¶

Method	Path	Description
`GET`	`/{name}/export`	Export agent as a standalone Python script

Export Agent¶

curl http://localhost:8000/api/v1/agents/my-agent/export -o my-agent.py

Generates a self-contained Python script that uses agentic-primitives-gateway-client for primitive calls (memory, browser, code interpreter) and raw boto3 Bedrock converse() for the LLM tool-call loop. The exported script:

Includes all tool definitions matching the agent's enabled primitives
Generates sub-agent delegation code if the agent uses agent-as-tool
Generates shared memory pool tools if shared_namespaces is configured
Handles JWT token refresh automatically
Manages browser/code_interpreter sessions with lazy initialization and cleanup

The response has Content-Type: text/x-python and Content-Disposition: attachment.

Session Cleanup¶

Method	Path	Description
`POST`	`/{name}/sessions/cleanup`	Delete old sessions, keeping the most recent N

Cleanup Sessions¶

curl -X POST "http://localhost:8000/api/v1/agents/my-agent/sessions/cleanup?keep=5"

{"deleted": 12, "kept": 5}

Deletes old sessions sorted by last activity, preserving the keep most recent ones (default: 5).

Introspection¶

Method	Path	Description
`GET`	`/{name}/tools`	List tools available to this agent with provider info
`GET`	`/{name}/memory`	Introspect memory stores (namespaces + contents)
`GET`	`/tool-catalog`	List all primitives and their available tools with input schemas

List Agent Tools¶

curl http://localhost:8000/api/v1/agents/my-agent/tools

{
  "agent_name": "my-agent",
  "tools": [
    {"name": "remember", "description": "Store information...", "primitive": "memory", "provider": "in_memory"},
    {"name": "recall", "description": "Retrieve a memory...", "primitive": "memory", "provider": "in_memory"}
  ]
}

Tool Catalog¶

curl http://localhost:8000/api/v1/agents/tool-catalog

Returns all available primitives and their tools, including JSON Schema input_schema for each tool. Clients can use this to dynamically build framework-specific tool wrappers.

{
  "primitives": {
    "memory": [
      {"name": "remember", "description": "Store information in long-term memory.", "input_schema": {"type": "object", "properties": {"key": {"type": "string"}, "content": {"type": "string"}}, "required": ["key", "content"]}},
      {"name": "recall", "description": "Retrieve a memory by its exact key.", "input_schema": {"type": "object", "properties": {"key": {"type": "string"}}, "required": ["key"]}}
    ],
    "code_interpreter": [...],
    "browser": [...],
    "tools": [...],
    "identity": [...],
    "shared_memory": [...],
    "task_board": [...],
    "agent_management": [...],
    "agents": []
  }
}