agentmanager

# 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:

```http
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 o