register_agent¶

Register a new sub-agent task.

Read-only: No

Description¶

Called by the primary session when dispatching sub-agents for parallel work. Provide the frontier item the agent should work on and optionally the relevant node IDs for its scoped subgraph view. The agent can then call get_agent_context with its task ID to receive its scoped view.

Parameters¶

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Unique identifier for the agent
`frontier_item_id`	`string`	Yes	ID of the frontier item this agent should work on
`subgraph_node_ids`	`string[]`	No	Node IDs relevant to this agent's task. Leave empty to auto-compute from the frontier item.
`skill`	`string`	No	Skill/methodology to apply

Returns¶

On success:

Field	Type	Description
`task_id`	`string`	Unique task ID (use this for `get_agent_context`, `update_agent`, and `agent_heartbeat`)
`agent_id`	`string`	The agent identifier
`status`	`string`	Initial status (`running`)
`scope_node_count`	`number`	Number of seed nodes snapshotted for the agent's subgraph
`scope_warning`	`string?`	Present when auto-scoped seeds resolved to zero nodes
`message`	`string`	Confirmation

On lease conflict (P1.4):

{
  "ok": false,
  "error": "frontier_lease_conflict",
  "frontier_item_id": "fi-...",
  "existing_task_id": "task-already-claimed",
  "existing_agent_id": "agent-already-running",
  "message": "Frontier item ... is already leased by task ... Pick a different item."
}

(Tool returns isError: true on the conflict path so the caller can branch cleanly.)

Frontier Lease (P1.4)¶

Each registration takes a TTL lease on the frontier item. While the lease is active, a different task cannot claim the same item — register_agent returns lease_conflict instead of racing.

Default lease TTL: 600 seconds.
Heartbeats from agent_heartbeat extend the lease for another full TTL window.
Terminal status (completed / failed / interrupted) releases the lease immediately.
The watchdog reaps expired leases on a 30-second interval, even when the owning task hasn't been touched.

For long-running agents, call agent_heartbeat every 30–60 seconds to prevent the lease (and the task itself) from being reaped as stale.

AgentTask Lifecycle Fields¶

The AgentTask returned from this tool, available later via get_state or update_agent, carries:

Field	Type	Description
`id`	`string`	Task ID (matches the returned `task_id`)
`agent_id`	`string`	Authoring agent
`assigned_at`	`string`	ISO timestamp set at registration
`status`	`"pending" \\| "running" \\| "completed" \\| "failed" \\| "interrupted"`	Current state
`frontier_item_id`	`string?`	Linked frontier item
`subgraph_node_ids`	`string[]`	Snapshotted seed nodes
`skill`	`string?`	Methodology hint
`completed_at`	`string?`	ISO timestamp on terminal status
`result_summary`	`string?`	Filled in by `update_agent` / `submit_agent_transcript`
`heartbeat_at`	`string?`	Most recent heartbeat (P0.3)
`heartbeat_ttl_seconds`	`number?`	Watchdog cutoff (default 120)

Tasks that never heartbeat are exempt from watchdog reaping — preserves backward-compat for tools that complete in a single MCP turn.

Usage Notes¶

The task_id returned is what agents use to get their scoped context.
If subgraph_node_ids is empty, the server eagerly snapshots seed nodes from the frontier item at registration time, so the scope survives frontier changes between registration and get_agent_context.
For network_discovery tasks, scope is always empty (CIDR context is provided instead).
If auto-scoping resolves to zero nodes, a scope_warning is returned so the operator can provide explicit scope or investigate.
Set skill to guide the agent toward a specific methodology.
Use update_agent to mark the task as completed or failed when done.
For long-running tasks, call agent_heartbeat periodically to keep the lease alive.