agent.*

Agent methods control Aleph's core AI execution loop (the Think→Act harness). agent.* is the direct entry used by panels and external integrations; chat-oriented clients normally use the chat.* family — both share the same execution adapter underneath.

Methods

Historical aliases such as agent.history / agent.clear / agent.respondToInput / agent.events are not RPCs. Use chat.history / chat.clear for session reads and events.* for streaming.

agent.run

Start an agent run. The handler returns immediately with a run_id; the actual response is delivered as streaming events on the stream.* and agent.* topics.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "agent.run",
  "params": {
    "input": "Summarize today's news",
    "session_key": "agent:main:main",
    "thinking": "medium"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "run_id": "run-uuid-123",
    "session_key": "agent:main:main",
    "accepted_at": "2026-03-15T10:00:00Z"
  }
}

Parameters:

Response fields:

agent.status

Look up the current state of a run by run_id.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "agent.status",
  "params": { "run_id": "run-uuid-123" }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "run_id": "run-uuid-123",
    "session_key": "agent:main:main",
    "status": "running",
    "elapsed_ms": 1247
  }
}

status is one of running / completed / failed / cancelled. An unknown run_id returns -32602 Invalid params.

agent.cancel

Cancel an in-flight run. The cancel token is forwarded to the execution adapter; the run stops at the next safe checkpoint and releases its resources.

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "agent.cancel",
  "params": { "run_id": "run-uuid-123" }
}

Response:

{ "jsonrpc": "2.0", "id": 3, "result": { "run_id": "run-uuid-123", "cancelled": true } }

cancelled indicates the cancel request was accepted; the transitional state until the run truly stops is visible via agent.status.

agent.list

List every agent registered in the AgentRouter plus the current default.

Request:

{ "jsonrpc": "2.0", "id": 4, "method": "agent.list" }

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "agents": [
      { "id": "main", "name": "Main", "enabled": true, "is_default": true }
    ],
    "default": "main"
  }
}

Each entry exposes id / name / enabled / is_default, exactly as returned by AgentRouter::list_agents().

Streaming Events

After agent.run is accepted, the event bus delivers run lifecycle changes as WebSocket notifications (topic names come from GatewayEventFrame::topic_name()):

Non-streaming events share the same bus:

Session Key Formats

The session_key parameter determines context isolation. See the Protocol page for WebSocket transport details.

Thinking Levels

thinking controls how much reasoning the agent performs before responding.

See Also

• Methods Reference -- All method namespaces
• events.* -- Subscribe to agent events
• chat.* -- Chat interface (chat.send / chat.abort / ...)
• session.* -- Session management