Agent Endpoints
Spawn, manage, and communicate with agents. Agents are autonomous entities with their own memory contexts, capable of processing messages and executing tasks using their accumulated knowledge.
Overview
The agent API lets you create and manage agents that have their own isolated memory contexts. Each agent accumulates episodic, semantic, and procedural memories through interactions. Agents can be members of hives to share collective knowledge.
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/agents/spawn | Spawn a new agent |
GET | /v1/agents | List agents |
GET | /v1/agents/:id | Get a specific agent |
PUT | /v1/agents/:id | Update an agent |
DELETE | /v1/agents/:id | Delete an agent |
POST | /v1/agents/:id/message | Send a message to an agent |
POST | /v1/agent-constellations/:id/runs | Start a run (Husk agents execute a multi-step loop) |
GET | /v1/agent-constellations/:id/thoughts | Read an agent's thought stream |
Spawn Agent
List Agents
Get Agent
Update Agent
Delete Agent
Destructive action
Deleting an agent permanently removes all of its memories and cannot be undone. Consider deactivating the agent instead by updating its status to inactive if you may need the agent or its memories later.
Send Message
Memory consultation
The memories_consulted field in the response shows which memories the agent used to inform its response, along with their relevance scores. This is useful for debugging and understanding the agent's reasoning.
Run Agent (Multi-Step)
Run loop semantics
The loop is bounded by maxSteps and a runtime budget (from the agent's maxRuntimeSeconds). A completed run reports a stopReason of answer (the agent finished), max_steps (step budget exhausted), or timeout (runtime budget exhausted). Per-step checkpoints are readable at GET /v1/agent-constellations/:id/checkpoints.
Thought Stream
Query parameters: sessionId (filter to one run's session), thoughtType (one of goal, recall, insight, action, result, reflection), and limit (default 50).
Agent Tokens
Scoped at_… credentials an agent authenticates with directly. Mint with the minimum scopes the agent needs (see Scopes & Permissions); the raw token is returned once at mint time — only metadata is listable afterwards. Tokens can also be managed from the agent's dashboard page.
GET /v1/agent-constellations/:id/tokens lists token metadata (never the secret); DELETE /v1/agent-constellations/:id/tokens/:tokenId revokes.
Memory Quota
Cap how many long-term memories an agent may accumulate. Once the cap is reached, further agent memory writes are rejected with a quota-exceeded error. A null quota means unlimited.
Agent Object
The following table describes all fields in an agent object.
| Field | Type | Description |
|---|---|---|
id | string | Unique agent identifier (prefixed with agent_) |
name | string | Human-readable agent name |
description | string | Agent description and purpose |
status | string | Agent status: active, inactive, terminated |
config | object | Agent configuration (model, temperature, memory settings) |
memory_count | integer | Total number of memories in the agent's context |
message_count | integer | Total messages processed by the agent |
hives | array | List of hive IDs the agent belongs to |
metadata | object | Arbitrary key-value metadata |
created_at | string | ISO 8601 creation timestamp |
last_active_at | string | ISO 8601 timestamp of last activity |
