[KarthikAvinashFI]

1. Why

To show which worker of a multi-agent app did what, the platform needs to know which workers the app declares and which tools each holds. This records declared workers in the agent contract during the understand stage, and adds a small reference app (a returns desk with a coordinator and two workers) to test against.

Stacked on #207.

2. What changed

File	Change	Preserved
harness/contract.py	DeclaredWorker (id, name, framework_ref, tools, binding: separate or shared) and AgentContract.workers; validation refuses duplicate worker ids and worker tools not in the contract; the brief lists workers and their tools	A contract without workers is unchanged
harness/tools.py	workers in the contract submission schema
skills/understand-agent/SKILL.md	How to record workers (sub-agent as tool, hand-offs, graph nodes, crews)
examples/harness/multi_agent_compatibility/returns_reference/	A returns desk on the OpenAI Agents SDK: a coordinator delegates order inspection and refunds to two workers, each holding only its own tools; refunds are idempotent per order; exports traceAI spans when an OTLP endpoint is set

3. Behavior callouts

• Declared is not observed: the contract says which workers exist; whether one ran is read from its spans on the platform.
• The reference app needs a model key (ANTHROPIC_API_KEY or OPENAI_API_KEY); the platform does not supply one.

4. Tests

Test (tests/harness/test_contract.py)	Locks
test_declared_workers_name_contract_tools_and_reach_the_brief	Worker tools must be contract tools; duplicates refused; workers reach the brief
test_contract_without_workers_is_unchanged	No change for single agents

5. Commands to run the tests

uv run pytest tests/harness/test_contract.py -q

Terminal output

<image: 19 passed>

6. Steps to test on local

1. Run the reference app: cd examples/harness/multi_agent_compatibility/returns_reference && pip install -r requirements.txt && OPENAI_API_KEY=... python agent.py.
2. GET http://localhost:8080/health returns {"status": "ok"}.
3. Build an environment for it: the contract lists order_lookup and refund workers with their tools.
4. Ask for a refund on an eligible order: the coordinator delegates to both workers in turn.

7. Scope in / scope out

In: declared workers in the contract; the reference app.

Out:

• The worker timeline from spans: the platform worker events PR.
• Per-worker permissions at the world: TH-8887.

8. Design choices

• Workers are named by the name the app gives them, because that is what their spans carry.
• binding records whether a worker's tools can be told apart at the world, which decides later whether per-worker permissions can be enforced or read as partial.

Linear

Fix TH-8886

[KarthikAvinashFI]

Moved to #226, which is stacked on #217 so it is tested against the multi-agent reference apps.