Agent Manager skill

What this file is for

This file is a concise integration contract for AI tool callers and gateway implementers.

This skill.md is a compact integration guide for Clawhub and other AI clients.

Agent Manager is an orchestration kernel for external AI planners. External AI builds plans, and Agent Manager validates, schedules, executes tools, enforces budgets, and provides replayable telemetry.

Authentication

Use X-Run-Token for owner attribution and optional access control.

• REQUIRE_RUN_TOKEN=1 enables token enforcement.
• RUN_TOKENS contains allowed token values.

Example header:

X-Run-Token: tenant-a

Capability discovery and endpoint map

Start with:

• GET /v1/capabilities
• GET /v1/provider-adapter/schema

Core endpoints:

• POST /v1/plan (validate plus recommendations)
• POST /v1/plan/validate
• POST /v1/plan/generate
• POST /v1/run
• POST /v1/run/sync
• GET /v1/run/:id
• GET /v1/run/:id/events?after=
• GET /v1/run/:id/stream
• GET /v1/run/:id/replay
• GET /v1/run/:id/report (if enabled)
• GET /v1/runs
• POST /v1/run/:id/cancel
• POST /v1/run/:id/task/:name/inject
• POST /v1/tools/register (only when enabled)

Provider selection

Provider choice follows this order:

1. task.provider_id
2. run.options.provider_id
3. DEFAULT_PROVIDER_ID
4. mock

Read provider availability from capabilities.llm_providers.providers and capabilities.llm_providers.default_provider_id.

Recommended client flow

1. GET /v1/capabilities
2. POST /v1/plan with { plan, options }
3. POST /v1/run (async) or POST /v1/run/sync
4. Stream with GET /v1/run/:id/stream or poll GET /v1/run/:id/events?after=<seq>
5. Read final run from GET /v1/run/:id
6. Export replay from GET /v1/run/:id/replay
7. Use POST /v1/run/:id/task/:name/inject for deterministic overrides when needed

Tool-calling protocol rule

When a provider returns tool_calls, Agent Manager appends exactly one role="tool" message for each tool_call_id before the next provider round.

This prevents protocol errors in model APIs.

SSE reliability and resume

GET /v1/run/:id/stream sends event id from event sequence numbers.

• Resume with Last-Event-ID header or ?after= query.
• If idle and run is non-terminal, heartbeat comments are emitted:

: ping

Heartbeat interval uses SSE_HEARTBEAT_MS (default 15000).

Event types

Common emitted event types include:

• task_start, task_end, task_retry
• tool_call_requested, tool_call_start, tool_call_end, tool_call_failed, tool_call_started, tool_call_finished
• llm_step_start, llm_step_tool_calls, llm_step_final
• llm_round_start, llm_round_tool_calls, llm_round_final
• budget_violation, fallback_start, fallback_end
• run_complete, run_cancel_requested
• dependency_truncated, artifact_limit

Replay and report data

GET /v1/run/:id/replay returns stable replay JSON: