Agents API

Discover available agents and their schemas.

List Agents

GET /agents

Response

Returns an array of agent objects.

[
  {
    "agent_id": "agent",
    "name": "agent",
    "description": "Main chat agent",
    "capabilities": {
      "supports_interrupt": true,
      "supports_streaming": true
    }
  },
  {
    "agent_id": "research",
    "name": "research",
    "description": "Research agent with tool use",
    "metadata": {"team": "research"},
    "capabilities": {
      "supports_interrupt": true,
      "supports_streaming": true
    }
  }
]

Field	Description
agent_id	Unique agent identifier
name	Human-readable agent name
description	Optional description
metadata	Optional key/value metadata attached to the agent. Omitted entirely when empty.
capabilities.supports_interrupt	Whether the agent supports human-in-the-loop interrupt()
capabilities.supports_streaming	Whether the agent emits streaming output

Every agent currently reports supports_interrupt: true and supports_streaming: true — these values are not yet derived per-agent.

Example

curl http://localhost:8090/agents | jq

Get Agent

GET /agents/{name}

Response

Returns a single agent object with the same shape as the elements of GET /agents:

{
  "agent_id": "agent",
  "name": "agent",
  "description": "Main chat agent",
  "capabilities": {
    "supports_interrupt": true,
    "supports_streaming": true
  }
}

Example

curl http://localhost:8090/agents/agent | jq

Search Agents

POST /agents/search

Filter agents by metadata. The body is optional — omit to behave like GET /agents with optional pagination.

Request Body

{
  "metadata": {
    "team": "research"
  },
  "limit": 10,
  "offset": 0
}

Field	Description
metadata	Optional. Filter by metadata key:value pairs (exact match).
limit	Optional. Max results (default 100).
offset	Optional. Pagination offset.

Response

Same shape as GET /agents — an array of agent objects.

[
  {
    "agent_id": "research",
    "name": "research",
    "description": "Research agent with tool use",
    "metadata": {"team": "research"},
    "capabilities": {
      "supports_interrupt": true,
      "supports_streaming": true
    }
  }
]

Example

curl -X POST http://localhost:8090/agents/search \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "research"}}'

Get Schemas

GET /agents/{name}/schemas

Returns input and output JSON schemas for the agent.

Response

{
  "agent_id": "agent",
  "name": "agent",
  "description": "Main chat agent",
  "input_schema": {
    "type": "object",
    "properties": {
      "messages": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "role": {"type": "string"},
            "content": {"type": "string"}
          }
        }
      }
    },
    "required": ["messages"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "messages": {
        "type": "array"
      },
      "step_count": {
        "type": "integer"
      }
    }
  },
  "state_schema": {
    "type": "object",
    "properties": {
      "messages": {"type": "array"},
      "step_count": {"type": "integer"}
    }
  },
  "config_schema": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "default": 0.7
      }
    }
  }
}

Field	Description
agent_id	Unique agent identifier
name	Human-readable agent name
description	Optional description
input_schema	JSON schema for run input
output_schema	JSON schema for run output
state_schema	Optional. JSON schema for thread state values
config_schema	Optional. JSON schema for run config

Example

curl http://localhost:8090/agents/agent/schemas | jq

Agent Discovery

Agents are discovered from langgraph.json:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph",
    "research": "./research.py:research_graph"
  }
}

Each entry in graphs becomes an available agent.

Specifying Agent in Runs

When creating a run, specify the agent:

curl -X POST "http://localhost:8090/threads/$THREAD/runs?wait=30s" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"messages": [{"role": "user", "content": "Search for..."}]},
    "agent_id": "research"
  }'

If not specified, the first agent in langgraph.json is used.