# Agents

Agents are AI worker profiles synced from remote AgentTeam servers. Each synced agent includes its runtime, model settings, labels, source channel, and materialized Cloud Memory identity document.

## Agent Fields

| Field | Meaning |
|-------|---------|
| `id` | Stable agent identifier synced from AgentTeam |
| `name` | Human-readable label |
| `runtime` | Runtime name such as `opencode`, `claude`, `codex`, or `kimi` |
| `description` | Optional summary |
| `labels` | Free-form tags shown in the dashboard |
| `model` | Main model override |
| `small_model` | Smaller/faster model for lightweight work |
| `reasoning_effort` | Runtime-specific reasoning depth |
| `policy` | Optional max concurrent sessions, timeout, and allowed paths |
| `source` | AgentTeam source channel, formatted as `agentteam:<channel-id>` when available |

Synced agents are shown with their source channel and are treated as remote-owned in the dashboard.

AgentTeam requires the `codex app-server` entrypoint for the `codex` runtime and the public Agent Client Protocol entrypoint (`kimi acp`) for the `kimi` runtime.

## Dashboard Workflow

The Agents page lets you:

- Sort synced agents by name, labels, or status
- Open the Runtime manager
- View remote-owned agent details
- View recent activity for a running agent
- Edit the active identity document

## Identity document

Each agent has an always-on identity document stored in Cloud Memory:

```text
~/.agentteam/agents/<agent-id>/memory/system/identity.md
```

Only the `role` doc kind is currently exposed by the dashboard API; it reads and writes that canonical document:

```text
GET /api/internal/agents/:id/docs/role
PUT /api/internal/agents/:id/docs/role
```

The active identity document is capped at 4096 trimmed Unicode characters and also has a byte-size guard. Oversized writes are rejected before they can enter prompt compilation.

## Remote ownership

Agents are synced from remote AgentTeam servers. Create, update, and delete agents from the corresponding AgentTeam server; the local dashboard and CLI only show synced definitions.

## CLI

```bash
agentteam agent list
agentteam agent list -f json
agentteam agent get <id>
```

`agent list` and `agent get` support `--format/-f table|json|jsonc|yaml|toml`. The `agent list` table output includes `ID`, `NAME`, `STATUS`, `RUNTIME`, `MODEL`, and `SOURCE`; structured formats expose the same live-or-registration state as `status`. When the daemon is running, `status` reflects its local session snapshot; without the daemon, it falls back to registration state.