Add real multi-agent specialist team example

CONTRIBUTING.md

@@ -97,6 +97,11 @@ The durable custom-tool gate scenario can be selected with
 its documented example aligned with the complete-barrier, partial-result,
 duplicate-result, worker-replacement, and interactive live-model assertions.
 
+The specialist-team user journey runs with
+`scripts/with-dev-env make demo-multi-agent-team`. Keep it aligned with the
+ordinary-child, Advisor, real-usage, completion-barrier, and persistent-follow-up
+contracts covered by the multi-agent service and runtime tests.
+
 Cookbook-derived examples describe real Mango user journeys, not probe-only
 demos. Keep an offline deterministic test for exact runtime and recovery
 invariants, and a runnable public-API example for the documented live-model

Makefile

@@ -21,6 +21,7 @@ MANGO_TEST_S3_BUCKET ?= mango-test
 MANGO_TEST_S3_ACCESS_KEY ?= minioadmin
 MANGO_TEST_S3_SECRET_KEY ?= minioadmin
 MANGO_EXAMPLE_MODEL_ID ?= $(MANGO_MODEL_ID)
+MANGO_EXAMPLE_ADVISOR_MODEL_ID ?= $(MANGO_EXAMPLE_MODEL_ID)
 
 DOCKER_BUILD_ARGS := --build-arg VERSION=$(VERSION) --build-arg REVISION=$(REVISION)
 ifneq ($(strip $(GOPROXY)),)
@@ -31,6 +32,7 @@ endif
 
 .PHONY: help build lint test test-race test-service test-model-live test-platform-live \
 	test-coding-agent test-coding-agent-live test-hitl-gate demo-hitl-gate \
+	demo-multi-agent-team \
 	vet verify security docs-check image image-smoke dev-env-init \
 	local-config local-up local-down local-health local-ps local-logs
 
@@ -47,6 +49,7 @@ help:
 	@echo "  make test-coding-agent-live  run the iterate scenario against the live model"
 	@echo "  make test-hitl-gate      run the durable custom-tool HITL scenario"
 	@echo "  make demo-hitl-gate      run the interactive HITL example over public HTTP"
+	@echo "  make demo-multi-agent-team  run the interactive multi-agent example over public HTTP"
 	@echo "  make vet            run go vet"
 	@echo "  make verify         run the core Go checks"
 	@echo "  make security       scan reachable Go code and high-severity npm issues"
@@ -122,6 +125,12 @@ demo-hitl-gate:
 	env -u MANGO_MODEL_BASE_URL -u MANGO_MODEL_API_KEY -u MANGO_MODEL_AUTH -u MANGO_MODEL_ID \
 		$(GO) run ./examples/hitl-gate
 
+demo-multi-agent-team:
+	MANGO_EXAMPLE_MODEL_ID='$(MANGO_EXAMPLE_MODEL_ID)' \
+	MANGO_EXAMPLE_ADVISOR_MODEL_ID='$(MANGO_EXAMPLE_ADVISOR_MODEL_ID)' \
+	env -u MANGO_MODEL_BASE_URL -u MANGO_MODEL_API_KEY -u MANGO_MODEL_AUTH -u MANGO_MODEL_ID \
+		$(GO) run ./examples/multi-agent-team
+
 vet:
 	$(GO) vet ./...
 

docs/capabilities.md

@@ -51,7 +51,7 @@ and service test suites.
 | [Vaults](api/vaults.md) | Limited | Encrypted Vault/Credential lifecycle, ordered Session attachment, OAuth validation, expiry refresh, and token rotation. Environment-variable egress and refresh-failure notifications are not implemented. |
 | [Deployments](api/deployments.md) | Limited | Deployment/Run lifecycle, pinned Agent Versions, Session budget templates, manual runs, cron scheduling, leases, and atomic success/failure records. Repository resources and Agent-archive propagation remain open. |
 | [Environment Work](api/environment-work.md) | Limited | Self-hosted worker leases, polling, heartbeats, state transitions, reclaim, and Session activation. Environment-key issuance, tenant-scoped authorization, Work secrets, and health-check Work remain open. |
-| [Multi-agent](guides/multi-agent.md) | Limited | Persistent ordinary child Agents plus primary-only Mango-managed Advisor consultations over client tool calls, independent transcripts/events/usage, shared Session budgets, reports, routing, interrupts, retries, archive, deletion, and durable context-compaction checkpoints. Broader live-provider evidence and targeted interruption timing remain open. |
+| [Multi-agent](guides/multi-agent.md) | Limited | Persistent ordinary child Agents plus primary-only Mango-managed Advisor consultations over client tool calls, independent transcripts/events/usage, shared Session budgets, reports, routing, interrupts, retries, archive, deletion, and durable context-compaction checkpoints. A real-provider specialist-team journey covers parallel delegation, Advisor consultation, synthesis, and persistent-Thread follow-up; repeated broader live-provider evidence and targeted interruption timing remain open. |
 | [Sandbox adapters](sandboxes.md) | Limited / Preview | Local and Docker are available. E2B, CubeSandbox, OpenSandbox, and Daytona have durable bindings, materialize File Resources and custom Skills, and publish Session Outputs through their official SDKs. Remote resource copies have documented limitations; E2B/Cube additionally buffer file transfers. Remote adapters remain Preview pending repeated live conformance and production routing policy. |
 | Distributed operation | Limited | API and worker roles scale independently around PostgreSQL, Temporal, and NATS. Worker Versioning, heterogeneous-provider routing, distributed Files reconciliation, and production rollout evidence remain open. |
 

docs/examples/multi-agent-team.md

@@ -0,0 +1,86 @@
+---
+title: Coordinate a specialist team
+slug: /examples/multi-agent-team
+---
+
+# Coordinate a specialist team
+
+This example runs a release-readiness review through Mango's public HTTP API.
+A coordinator delegates independent work to reliability and security Agents,
+consults an Advisor, waits for all three responses, and produces a decision. A
+second interactive turn adds a new constraint and must continue the existing
+reliability Thread instead of creating another one.
+
+Every inference in the documented run uses the real model endpoint configured
+on the Mango worker. The example client has no model-provider credentials and
+does not invoke a hosted agent service. It also uses no simulated GitHub, web,
+database, or other third-party boundary: the workflow exercises only Mango's
+Agents, Session, Events, and Session Threads.
+
+## What the run proves
+
+The program checks observable product behavior rather than matching exact model
+wording:
+
+1. The coordinator starts exactly one `reliability_reviewer` Thread and one
+   `security_reviewer` Thread.
+2. Both specialists return non-empty reports with real provider token usage.
+3. The coordinator does not produce its decision until both specialist reports
+   and the configured Advisor's challenge are available. The model may consult
+   the Advisor concurrently with the specialists.
+4. The Advisor appears as one automatically terminated
+   `{"type":"advisor"}` Session Thread with its own usage.
+5. The terminal user supplies a follow-up constraint.
+6. The coordinator addresses the existing reliability Thread with
+   `session_thread_id` and waits for its new report.
+7. The follow-up increases usage on that same Thread without creating another
+   specialist or Advisor Thread.
+
+Mango's ordinary offline service tests cover the deterministic delegation,
+Advisor, persistence, retry, interrupt, and follow-up invariants. This example
+adds the explicitly opt-in real-model evidence that public CI cannot provide.
+
+## Run the example
+
+Configure `MANGO_MODEL_*` in `~/.config/mango/dev.env` as described in
+[Getting started](../getting-started.md). Start the local stack with that
+environment so its worker uses the real Messages-shaped endpoint:
+
+```bash
+scripts/with-dev-env make local-up
+make local-health
+```
+
+Then run the public-HTTP client:
+
+```bash
+scripts/with-dev-env make demo-multi-agent-team
+```
+
+The Make target passes the configured model IDs to the example but removes the
+provider base URL and key from the client process. Set
+`MANGO_EXAMPLE_ADVISOR_MODEL_ID` when the Advisor should use a different model;
+otherwise it uses `MANGO_EXAMPLE_MODEL_ID`.
+
+After the first decision, the terminal asks for another release constraint.
+Enter one or press Return to use the displayed default. The real coordinator
+must route it through the persistent reliability Thread before returning a
+revised decision.
+
+Set `MANGO_EXAMPLE_KEEP_RESOURCES=1` to retain the Session, three Agent
+resources, and Environment for inspection. Otherwise the program deletes the
+Session and Environment and archives the Agents after the verification.
+
+## Design boundary
+
+The specialist-team user problem is informed by Anthropic's public
+[`CMA_coordinate_specialist_team` cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/managed_agents/CMA_coordinate_specialist_team.ipynb).
+Mango adopts the useful coordinator, scoped specialist, persistent Thread, and
+Advisor workflow. It replaces the hosted data, web-search, SDK, and
+`send_to_parent` presentation with synthetic release facts, Mango's public HTTP
+API, and runtime-owned child completion reports.
+
+The example does not define Mango's multi-agent contract and adds no
+scenario-specific runtime behavior. See
+[Run a multi-agent Session](../guides/multi-agent.md) for the reusable workflow
+and [Session Threads](../api/session-threads.md) for the HTTP contract.

docs/getting-started.md

@@ -194,18 +194,25 @@ scripts/with-dev-env make test-coding-agent-live
 # Runs the public-HTTP expense gate example. The real model generates the
 # decide/escalate calls and the terminal prompts for the human decision.
 scripts/with-dev-env make demo-hitl-gate
+
+# Runs a real coordinator, two specialist Agents, one Advisor consultation,
+# and an interactive follow-up on a persistent child Thread.
+scripts/with-dev-env make demo-multi-agent-team
 ```
 
 The [coding-agent iteration example](examples/coding-agent-iterate.md) explains the
 corresponding user workflow and the Mango resources involved. It is a design
 walkthrough rather than a second test runner. The
 [HITL gate example](examples/hitl-gate.md) documents the interactive public-HTTP
-example and its application-owned action boundary.
+example and its application-owned action boundary. The
+[specialist-team example](examples/multi-agent-team.md) verifies real-model
+delegation, Advisor usage, and persistent Thread follow-up.
 
 These commands never print the API key. The model-only smoke test does not
 enable tools; the platform tests use an isolated Docker sandbox, the coding
 scenario excludes Web Search/Fetch from its least-privilege toolset, and the
-HITL example removes provider credentials from its client process. Live checks
+interactive examples remove provider credentials from their client processes.
+Live checks
 are excluded from public CI because external credentials, availability,
 latency, user input, and cost are not deterministic.
 Use a newly issued key if a credential has ever appeared in chat, logs, or shell

docs/guides/multi-agent.md

@@ -13,6 +13,10 @@ Multi-agent execution uses the ordinary Session and Event APIs. Delegation is
 not a client-side endpoint: a coordinator receives the private `list_agents`
 and `send_to_agent` model tools and decides when to call them.
 
+For a runnable public-HTTP scenario with a real coordinator, two specialists,
+an Advisor, and persistent follow-up, see
+[Coordinate a specialist team](../examples/multi-agent-team.md).
+
 ## Prerequisites
 
 - Complete [Getting started](../getting-started.md).

docs/provenance.md

@@ -168,6 +168,31 @@ support, so they run the same offline and opt-in live conformance suites.
   assumptions. Durable outbound webhook delivery remains separate work with
   its own signing, retry, idempotency, and observability requirements.
 
+## Multi-agent specialist team
+
+- Anthropic's public
+  [`CMA_coordinate_specialist_team` cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/managed_agents/CMA_coordinate_specialist_team.ipynb)
+  supplied the useful specialist-team user problem: a coordinator delegates
+  role-scoped work, waits for reports, consults an Advisor, and synthesizes a
+  final decision.
+- Mango's real-model example adopts that high-level workflow but uses synthetic
+  release-readiness facts and no Web, hosted data, or third-party integration.
+  The client exercises Mango's public HTTP resources and inspects its persisted
+  Event and Session Thread projections.
+- Mango changes child completion semantics deliberately. Ordinary child Agents
+  finish a turn and the runtime projects their report to the coordinator; they
+  do not receive or need a hosted `send_to_parent` tool. Persistent follow-up is
+  addressed through Mango's runtime-owned `send_to_agent` tool and the existing
+  `session_thread_id`.
+- The scenario verifies one real provider run with two ordinary children, a
+  primary-only Advisor consultation, per-Thread usage, a final synthesis
+  barrier, and an interactive follow-up. Deterministic service tests remain
+  authoritative for retry, interruption, recovery, archive, and deletion
+  invariants.
+- Mango did not adopt the Cookbook's SDK calls, cloud Environment fields,
+  bundled sales collateral, web-search dependency, hosted model restrictions,
+  or exact response text.
+
 ## Custom Skills
 
 - The public [Claude Managed Agents Skills guide](https://platform.claude.com/docs/en/managed-agents/skills)