Agents API

Create, manage, and interact with agents.

Create Agent

POST /v1/agents

Request

{
  "name": "researcher",
  "persona": "You are a research assistant specialized in academic papers.",
  "config": {
    "model": "gpt-4o",
    "provider": "openai",
    "temperature": 0.7
  }
}

Parameters

Field	Type	Required	Description
name	string	Yes	Unique agent name
persona	string	No	System persona for the agent
config	object	No	Model and provider configuration

Response (201)

{
  "name": "researcher",
  "persona": "You are a research assistant specialized in academic papers.",
  "config": {
    "model": "gpt-4o",
    "provider": "openai",
    "temperature": 0.7
  },
  "created_at": "2025-03-15T10:00:00Z"
}

List Agents

GET /v1/agents

Response (200)

[
  {
    "name": "researcher",
    "created_at": "2025-03-15T10:00:00Z"
  },
  {
    "name": "devops",
    "created_at": "2025-03-16T14:30:00Z"
  }
]

Get Agent

GET /v1/agents/{name}

Response (200)

{
  "name": "researcher",
  "persona": "You are a research assistant specialized in academic papers.",
  "config": {
    "model": "gpt-4o",
    "provider": "openai",
    "temperature": 0.7
  },
  "skills": [
    {"id": "sk_abc", "name": "web_search"}
  ],
  "created_at": "2025-03-15T10:00:00Z"
}

Update Agent

PATCH /v1/agents/{name}

Request

{
  "persona": "Updated persona text for the agent.",
  "config": {
    "temperature": 0.5
  }
}

All fields are optional. Only provided fields are updated.

Response (200)

{
  "name": "researcher",
  "persona": "Updated persona text for the agent.",
  "config": {
    "model": "gpt-4o",
    "provider": "openai",
    "temperature": 0.5
  },
  "created_at": "2025-03-15T10:00:00Z"
}

Delete Agent

DELETE /v1/agents/{name}

Response (204)

No content.

Start a Run

POST /v1/agents/{name}/runs

Starts an agent run with the given prompt. The agent processes the prompt, potentially invoking skills and primitives, and produces a response. Monitor progress in real time via the SSE event stream at /v1/events/stream.

Request

{
  "prompt": "Find the top 5 most cited papers on transformer architectures from 2024."
}

Response (200)

{
  "run_id": "run_550e8400",
  "agent": "researcher",
  "status": "started"
}

Monitoring a Run

Subscribe to the SSE stream filtered by run_id to observe the run in real time:

curl -N "http://127.0.0.1:3000/v1/events/stream?run_id=run_550e8400"

Events you will see include run.started, message.assistant, skill.invoked, skill.completed, model.request, model.response, and run.completed (or run.failed).

Stop Agent

POST /v1/agents/{name}/stop

Stops a currently running agent, cancelling any active run.

Response (200)

{
  "agent": "researcher",
  "status": "stopped"
}

Reset Session

POST /v1/agents/{name}/reset

Resets the agent's conversation session, clearing short-term memory context.

Response (200)

{
  "agent": "researcher",
  "status": "reset"
}

Get Conversation History

GET /v1/agents/{name}/history

Returns the conversation history for the agent.

Response (200)

[
  {
    "role": "user",
    "content": "Find papers on transformer architectures.",
    "timestamp": "2025-03-15T10:00:00Z"
  },
  {
    "role": "assistant",
    "content": "I found several relevant papers...",
    "timestamp": "2025-03-15T10:00:05Z"
  }
]

Answer Agent Question

POST /v1/agents/{name}/ask-responses/{question_id}

When an agent asks a clarifying question during a run (via the ask primitive), this endpoint submits the answer.

Request

{
  "answer": "Focus on papers with more than 1000 citations."
}

Response (200)

{
  "question_id": "q_abc123",
  "status": "answered"
}