README
¶
team-agent-workflow
This live showcase runs one leader with three delegated local roles:
leader -> plan (read-only) -> impl (workspace-write) -> review (read-only)
The leader receives one delegate_to_agent MCP tool from
hosttools/a2adelegation. Role progress rejoins the leader's single typed
event stream as SubagentUpdate, and the AG-UI bridge exposes that same stream
to a browser as live activityType="subagent" messages. The CopilotKit page
keeps the leader chat on the left and renders plan, implementation, and review
cards in the right sidebar. Each card identifies its real provider base
(Claude Code, Codex, Cursor, or CodeBuddy) rather than displaying the
shared A2A transport label.
The read-only plan role has a per-call WithSchema[planFileArtifact] contract.
It returns a structured PLAN.md value (filename, media_type, summary,
and Markdown content) without writing into the workspace. The AG-UI terminal
activity preserves that value, and the plan card renders it as a previewable,
downloadable file attachment.
One-command CopilotKit verification
Choose the local CLI explicitly and run:
./examples/showcases/team-agent-workflow/start-all.sh claude
./examples/showcases/team-agent-workflow/start-all.sh codex
./examples/showcases/team-agent-workflow/start-all.sh codebuddy
The script:
- installs the lockfile-pinned frontend dependencies when needed;
- builds and starts this Go backend on
127.0.0.1:8080; - waits for
/healthwithout starting an Agent run; - builds and starts the maintained CopilotKit frontend on
127.0.0.1:3000in team-workflow mode; and - shuts the backend down when the frontend exits.
Open http://127.0.0.1:3000. The request is already filled in, so click Send
to begin. Loading the page and probing /health are free. Every submitted
message makes one real leader call plus three real role calls and can incur
provider charges.
Additional role flags are passed to the Go command:
./examples/showcases/team-agent-workflow/start-all.sh claude \
-plan=codex -impl=claude -review=codex
Useful environment overrides:
| Variable | Default | Purpose |
|---|---|---|
TEAM_ADDR |
127.0.0.1:8080 |
Backend listen address |
TEAM_BACKEND_BASE_URL |
http://127.0.0.1:8080 |
Browser-reachable backend base URL |
TEAM_UI_PORT |
3000 |
CopilotKit server port |
TEAM_UI_ORIGIN |
http://127.0.0.1:$TEAM_UI_PORT |
Exact allowed browser origin |
TEAM_TIMEOUT |
2h |
Lifetime of the backend process |
TEAM_ROLE_TIMEOUT |
4m |
Maximum duration of one delegation |
KEEP_WORKSPACE |
0 |
Set to 1 to retain the temporary workspace on shutdown |
When changing the listen address for remote access, also set the corresponding browser-reachable URL and exact UI origin. Do not expose this paid endpoint with a wildcard CORS policy.
CLI-only verification
To run the deterministic workflow once and print its JSON audit verdict:
go run ./examples/showcases/team-agent-workflow -leader=claude -keep-workspace
The terminal run validates delegation order, ensures only impl changes the
workspace, requires the review approval sentinel, and checks the final
SOLUTION.md fixture.
Documentation
¶
Overview ¶
Host-side scaffolding for the team-agent-workflow showcase: the temporary task fixture, the workspace stage audit, the terminal renderer, and the protocol text handed to the leader.
None of this touches the SDK on purpose. It is here to keep main.go about the three SDK constructions that matter (Agent, delegation.Service, team.Option) and to make the point that everything below is host business the SDK deliberately does not model.
Command team-agent-workflow is the v1 team-collaboration showcase (design doc §9.7 / §9.8): one leader Agent drives three delegated roles — plan (read-only) -> impl (workspace-write) -> review (read-only) — through the host-injected delegate_to_agent MCP tool, and the whole team's progress arrives on the leader's single event stream.
What the SDK contributes here, in three lines of construction:
- delegation.NewService(...) is the entire delegation runtime: registry, event bus, delegator, per-run MCP sidecar (loopback listener, random bearer token, http.Server lifecycle) and result recording. The pre-v1 version of this showcase hand-wrote 323 lines for exactly this.
- delegation.Local(key, runner, policy) registers an in-process Runner as a delegatable role, so each role is one *adaptor.Agent value wrapped in an ordinary host decorator — no per-role SDK instance, no A2A server, no port to manage.
- team.Option() attaches the service to the leader in one option: the sidecar is declared as a runtime service with a typed MCP endpoint, its lifecycle is bound to the run, and every delegation event is folded into the leader's own Events() channel as adaptor.SubagentUpdate.
Everything else — the temporary workspace fixture, the terminal renderer, the workspace stage audit, and the protocol text handed to the leader — is plain host logic and lives in host.go.
LIVE ONLY, and it costs real money: one leader run plus three role runs against the selected local CLIs. There is therefore no default agent (-leader is required), no fallback that picks one for you, and no test ever invokes main or a local CLI. It is not part of examples/run_examples.ps1.
Usage:
./examples/showcases/team-agent-workflow/start-all.sh claude go run ./examples/showcases/team-agent-workflow -leader=claude go run ./examples/showcases/team-agent-workflow -leader=claude -plan=codex -review=codex go run ./examples/showcases/team-agent-workflow -leader=claude -keep-workspace go run ./examples/showcases/team-agent-workflow -leader=claude -web-mode go run ./examples/showcases/team-agent-workflow -leader=claude -web-mode -web-addr=0.0.0.0:8080 -web-cors=https://chat.example.com
Source Files