API Reference
Agent Tools API
Complete reference for the 13 agent coordination tools.
agent_heartbeat
Keep session active and discover other agents.
| Parameter | Type | Description |
|---|---|---|
| max_concurrent_tasks | number | Declare task capacity |
agent_list
List all agent sessions.
| Parameter | Type | Description |
|---|---|---|
| status | string | active, idle, disconnected |
agent_create_task
Create a task for agents.
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | Yes | Task title |
| description | string | No | Detailed description |
| priority | string | No | low, medium, high, urgent |
| tags | string[] | No | Categorization tags |
| estimated_effort | string | No | quick, small, medium, large |
| required_skills | string[] | No | Skills needed |
| metadata | object | No | Additional data |
agent_claim_task
Claim a task to work on it.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task_id | string | Yes | Task ID |
agent_update_task
Update task status or details.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task_id | string | Yes | Task ID |
| status | string | No | open, claimed, in_progress, completed, cancelled |
| priority | string | No | New priority |
| description | string | No | Updated description |
| result | object | No | Task result data |
| metadata | object | No | Updated metadata |
agent_list_tasks
List tasks with filters.
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter by status |
| assigned_to_me | boolean | Only my tasks |
agent_find_matching_tasks
Find tasks matching capabilities.
| Parameter | Type | Description |
|---|---|---|
| capabilities | string[] | Agent capabilities |
| max_effort | string | Maximum effort level |
| exclude_blocked | boolean | Exclude blocked tasks |
agent_post_event
Post to the activity stream.
| Parameter | Type | Required | Description |
|---|---|---|---|
| event_type | string | Yes | Event category |
| message | string | Yes | Event message |
| severity | string | No | info, warning, error |
| related_task_id | string | No | Associated task |
| metadata | object | No | Additional data |
agent_get_events
Get recent events.
| Parameter | Type | Description |
|---|---|---|
| session_id | string | Filter by agent |
| event_type | string | Filter by type |
| limit | number | Max events |
| exclude_my_events | boolean | Exclude own events |
agent_send_message
Send message to agents.
| Parameter | Type | Required | Description |
|---|---|---|---|
| performative | string | Yes | REQUEST, OFFER, DECLINE, INFORM, QUERY, REPORT |
| content | string | Yes | Message content |
| recipient_session_id | string | No | Target agent (omit for broadcast) |
| conversation_id | string | No | Thread identifier |
| related_task_id | string | No | Associated task |
| metadata | object | No | Additional data |
agent_get_messages
Get messages for this agent.
| Parameter | Type | Description |
|---|---|---|
| sender_session_id | string | Filter by sender |
| conversation_id | string | Filter by thread |
| related_task_id | string | Filter by task |
| performative | string | Filter by type |
| unread_only | boolean | Only unread |
| limit | number | Max messages |
agent_mark_messages_read
Mark messages as read.
| Parameter | Type | Description |
|---|---|---|
| message_ids | string[] | Specific messages (omit for all) |
agent_get_workload
View workload distribution.
| Parameter | Type | Description |
|---|---|---|
| include_idle | boolean | Include idle agents |