From 11f8d99b73d5bcca87e01952ccb441a41a6d1f06 Mon Sep 17 00:00:00 2001 From: Nathan Flurry Date: Thu, 5 Feb 2026 11:20:18 -0800 Subject: [PATCH] docs: add agent teams API and CLI notes --- .turbo | 1 + dist | 1 + docs/agent-teams.mdx | 86 +++++++++++++++++++++++++++++++++++++++ docs/docs.json | 1 + node_modules | 1 + research/agents/claude.md | 40 ++++++++++++++++++ target | 1 + 7 files changed, 131 insertions(+) create mode 120000 .turbo create mode 120000 dist create mode 100644 docs/agent-teams.mdx create mode 120000 node_modules create mode 120000 target diff --git a/.turbo b/.turbo new file mode 120000 index 0000000..0b7d9ca --- /dev/null +++ b/.turbo @@ -0,0 +1 @@ +/home/nathan/sandbox-agent/.turbo \ No newline at end of file diff --git a/dist b/dist new file mode 120000 index 0000000..f02d77f --- /dev/null +++ b/dist @@ -0,0 +1 @@ +/home/nathan/sandbox-agent/dist \ No newline at end of file diff --git a/docs/agent-teams.mdx b/docs/agent-teams.mdx new file mode 100644 index 0000000..67f65ef --- /dev/null +++ b/docs/agent-teams.mdx @@ -0,0 +1,86 @@ +--- +title: "Agent Teams" +description: "Notes on Claude Code agent teams and a proposed Sandbox Agent API." +icon: "users" +--- + +## Claude Code team model (external) + +Claude Code exposes agent teams as an interactive feature, not a public API. Key points from the upstream docs: + +- Enablement: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in env or settings.json. +- Display mode: `--teammate-mode` supports `auto`, `in-process`, `tmux`. +- Teams are created in natural language by the lead; teammates are independent sessions. +- Storage: + - `~/.claude/teams/{team-name}/config.json` + - `~/.claude/tasks/{team-name}/` +- Team concepts: lead, teammates, shared task list, mailbox for messaging. +- No documented CLI subcommand or Agent SDK API for team management. + +## Current gap in Sandbox Agent + +Sandbox Agent controls a single agent session at a time. Claude Code team state and teammate coordination do not surface through the `stream-json` CLI output, so there is no native team lifecycle to convert into the universal schema yet. + +## Proposed API shape (new resource) + +Add a Team resource and treat a team as a first-class container for multiple sessions: + +### Endpoints + +- `POST /v1/teams/{team_id}` + - Create a team and optionally create a lead session. +- `GET /v1/teams` + - List teams with summary metadata. +- `GET /v1/teams/{team_id}` + - Get team metadata and members. +- `POST /v1/teams/{team_id}/members` + - Spawn a teammate session (agent + mode + model + permission mode). +- `POST /v1/teams/{team_id}/members/{member_id}/messages` + - Send a message to a specific teammate. +- `POST /v1/teams/{team_id}/messages` + - Broadcast a message to all teammates. +- `POST /v1/teams/{team_id}/tasks` + - Create a task in the shared list. +- `PATCH /v1/teams/{team_id}/tasks/{task_id}` + - Update task state (pending/in_progress/completed) or assignment. +- `POST /v1/teams/{team_id}/terminate` + - Stop all sessions and clean up team resources. + +### CLI mapping (proposed) + +``` +sandbox-agent api teams list +sandbox-agent api teams create --agent claude --agent-mode code +sandbox-agent api teams members add --agent claude --model sonnet +sandbox-agent api teams members message --message "..." +sandbox-agent api teams broadcast --message "..." +sandbox-agent api teams tasks create --title "..." +sandbox-agent api teams tasks update --status completed +sandbox-agent api teams terminate +``` + +### Event extensions (proposed) + +Add optional team-aware events to the session transcript schema. These would be emitted by the daemon when it orchestrates teams, and marked `source=daemon` for agents without native team events: + +- `team.created` / `team.ended` +- `team.member.added` / `team.member.removed` +- `team.message.sent` (for teammate or broadcast messages) +- `team.task.created` / `team.task.updated` + +Each event should include `team_id` and, where relevant, `member_id` or `task_id`. + +### Session linkage (minimal change) + +Add an optional `team_id` field to `CreateSessionRequest` so existing session endpoints can still be used while associating sessions to a team container. + +## Compatibility strategy + +- Claude Code: Sandbox Agent would manage the team abstraction itself (multiple CLI sessions), since there is no public team API. +- Other agents: Teams are supported as a daemon-level orchestration feature; events are synthetic and marked accordingly. + +## Open questions + +- Should team tasks live in the universal schema or remain a daemon-only construct? +- Do we need a mailbox API for cross-agent messages, or are per-member messages enough? +- How should team cleanup interact with per-session termination and resume behavior? diff --git a/docs/docs.json b/docs/docs.json index 5e71ba9..12a4196 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -65,6 +65,7 @@ "cli", "opencode-compatibility", "inspector", + "agent-teams", "session-transcript-schema", "cors", { diff --git a/node_modules b/node_modules new file mode 120000 index 0000000..501480b --- /dev/null +++ b/node_modules @@ -0,0 +1 @@ +/home/nathan/sandbox-agent/node_modules \ No newline at end of file diff --git a/research/agents/claude.md b/research/agents/claude.md index 42a552b..9db9c65 100644 --- a/research/agents/claude.md +++ b/research/agents/claude.md @@ -65,6 +65,7 @@ claude \ --output-format stream-json \ --verbose \ --dangerously-skip-permissions \ + [--teammate-mode in-process|tmux|auto] \ [--resume SESSION_ID] \ [--model MODEL_ID] \ [--permission-mode plan] \ @@ -82,6 +83,7 @@ claude \ | `--resume SESSION_ID` | Resume existing session | | `--model MODEL_ID` | Specify model (e.g., `claude-sonnet-4-20250514`) | | `--permission-mode plan` | Plan mode (read-only exploration) | +| `--teammate-mode ` | Agent teams display mode: `auto`, `in-process`, `tmux` | ### Environment Variables @@ -196,6 +198,44 @@ Claude supports spawning subagents via the `Task` tool with `subagent_type`: - Custom agents defined in config - Built-in agents like "Explore", "Plan" +## Agent Teams (Experimental) + +Claude Code supports multi-session teams where a lead coordinates multiple teammates. Teams are disabled by default and must be enabled explicitly. + +### Enablement + +- **Environment flag**: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` +- **settings.json**: `{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }` + +### CLI additions + +- `--teammate-mode` controls display mode for teammates: `auto` (default), `in-process`, `tmux`. +- Teams are created via natural language in interactive mode; there is no dedicated CLI subcommand. + +### Team components and storage + +- **Lead**: the session that creates and manages the team. +- **Teammates**: independent Claude Code instances with their own context. +- **Task list**: shared task tracker used for coordination. +- **Mailbox**: internal messaging between teammates and lead. + +Claude stores team metadata locally: + +- `~/.claude/teams/{team-name}/config.json` +- `~/.claude/tasks/{team-name}/` + +### Known limitations (from docs) + +- No session resumption for in-process teammates (`/resume` does not restore them). +- Task status can lag; teammates may not mark tasks as completed. +- Shutdown can be slow (teammates finish current requests before exiting). +- One team per session; no nested teams. +- Teammate permission mode inherits from the lead at spawn time. + +### API surface notes + +The public Agent SDK and CLI documentation do not describe a dedicated API for team management. Team coordination appears to be interactive-first, with state persisted locally (paths above). No streaming event types for team lifecycle are documented in the CLI/SDK references. + ### ExitPlanMode (Plan Approval) When in `plan` permission mode, agent invokes `ExitPlanMode` tool to request execution: diff --git a/target b/target new file mode 120000 index 0000000..3d6ad8c --- /dev/null +++ b/target @@ -0,0 +1 @@ +/home/nathan/sandbox-agent/target \ No newline at end of file