# Multi-Agent System Design: [System name]

> Design document for a system in which several AI agents cooperate on
> one goal: goals and scope, the agent roster, the topology, handoff and
> delegation contracts, shared state and memory, inter-agent
> communication, loop, cost and time budgets, failure isolation and
> cascading-failure controls, observability, human oversight, threat
> mapping, evaluation and rollout. Threats are mapped to the OWASP Top
> 10 for Agentic Applications 2026 (ASI01 to ASI10, published December
> 2025). Agents that cross a trust or organisational boundary are
> assumed to talk over the Agent2Agent (A2A) protocol, specification
> 1.0 (1.0.1); agents reach tools over the Model Context Protocol (MCP),
> revision 2026-07-28. Replace every `[bracketed]` value and every row
> marked *Example*. Worked examples use a procurement assistant that
> triages purchase requests, checks suppliers and drafts orders.

<!--
Guidance: How to use this template
- Write one document per multi-agent system. Each agent in the roster
  still needs its own AI agent specification (`ai-data/ai-agent-spec`);
  this document covers what happens between agents.
- Fill section 2 honestly before anything else. Most tasks are better
  served by one agent with good tools; extra agents add latency, cost,
  new trust boundaries and new failure modes.
- Draw the topology (section 4) before writing contracts. Every arrow in
  the diagram needs a contract row in section 5 and a budget in section 8.
- Treat every message from another agent as untrusted data, even when
  your team owns that agent. A compromised or confused peer is the core
  threat in sections 9 and 11.
- Related documents: AI agent specification (`ai-data/ai-agent-spec`),
  MCP server specification (`ai-data/mcp-server-spec`), A2A Agent Card  and interface specification (`ai-data/a2a-agent-card-spec`), Agent  tool and permission design (`ai-data/agent-tool-permission-design`),
  Human oversight design (`ai-data/human-oversight-design`), Agentic  threat model (`ai-data/agentic-threat-model`), Agent evaluation plan (`ai-data/agent-evaluation-plan`), LLM observability specification (`ai-data/llm-observability-spec`).
-->

## Document control

<!-- Guidance: Identify the system version this design describes, the agents it includes and who approved it for which environment. A change to the roster or topology is a new version. -->

| Field | Value |
|---|---|
| Document ID | [MAS-DES-001] |
| System name and version | [Name] [v1.0.0] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Retired] |
| Owner | [@system-owner] |
| Approvers/reviewers | [@architect], [@security-engineer], [@ai-governance], [@business-owner] |
| Agents in scope | [MAS-AGT-001 to MAS-AGT-005] |
| Protocols | [A2A 1.0 (`A2A-Version: 1.0`)], [MCP 2026-07-28] |
| Deployment environments | [Staging / Production / Internal only] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related documents | [Agent specifications], [Agentic threat model], [Agent evaluation plan], [Runbook] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| System owner | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Architecture review | [@name] | [Decision] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| AI governance | [@name] | [Decision] | YYYY-MM-DD |
| Business process owner | [@name] | [Decision] | YYYY-MM-DD |

## Revision history

<!-- Guidance: Record every change to the roster, topology, contracts, budgets or autonomy. Each one changes system behaviour and needs the evaluation suites in section 13 to be re-run. -->

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved for production with orchestrator and three workers |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added external supplier agent over A2A behind approval gate MAS-HOV-002 |

## Contents

<!-- Guidance: Keep aligned with the headings below. -->

1. [Goals and scope](#1-goals-and-scope)
2. [Decision to use multiple agents](#2-decision-to-use-multiple-agents)
3. [Agent roster and responsibilities](#3-agent-roster-and-responsibilities)
4. [Topology](#4-topology)
5. [Handoff and delegation contracts](#5-handoff-and-delegation-contracts)
6. [Shared state and memory](#6-shared-state-and-memory)
7. [Inter-agent communication](#7-inter-agent-communication)
8. [Loop, cost and time budgets](#8-loop-cost-and-time-budgets)
9. [Failure isolation and cascading-failure controls](#9-failure-isolation-and-cascading-failure-controls)
10. [Human oversight points](#10-human-oversight-points)
11. [Threat mapping (OWASP Agentic Top 10 2026)](#11-threat-mapping-owasp-agentic-top-10-2026)
12. [Observability](#12-observability)
13. [Evaluation](#13-evaluation)
14. [Rollout and change control](#14-rollout-and-change-control)
15. [Traceability matrix](#15-traceability-matrix)
16. [Glossary and references](#16-glossary-and-references)

## 1. Goals and scope

<!-- Guidance: State the outcome the system as a whole produces, who it serves and where its boundary is. Goals must be testable, because section 13 measures them. Pitfall: describing what each agent does instead of what the system achieves. -->

### 1.1 System goal

[One sentence stating the outcome the system produces.] *Example:* Turn
an employee's purchase request into an approved, policy-compliant draft
purchase order within one working day, with supplier risk checked and a
human buyer signing off every order.

### 1.2 Goals and non-goals

| ID | Goal | Measure | Target |
|---|---|---|---|
| MAS-G-001 *(Example)* | Shorten request-to-draft time | Median elapsed time | Under 4 working hours |
| MAS-G-002 *(Example)* | Keep orders within policy | Share of drafts passing policy audit | At least 98% |
| MAS-G-003 *(Example)* | Never commit spend without a human | Orders submitted without buyer approval | Zero |

| Non-goal | Reason |
|---|---|
| *Example:* Negotiating prices with suppliers | Legal and commercial risk; stays with buyers |
| *Example:* Paying invoices | Handled by the finance system, outside this design |

### 1.3 Users, principals and boundaries

| Principal | Relationship | May instruct agents? |
|---|---|---|
| *Example:* Requesting employee | Submits the request | Yes, through the intake agent only |
| *Example:* Buyer (human) | Approves drafts, overrides agents | Yes, at oversight points |
| *Example:* External supplier agent | Remote A2A server run by a supplier | No: its replies are data |
| *Example:* ERP system | Tool backend over MCP | No |

## 2. Decision to use multiple agents

<!-- Guidance: Justify each extra agent. Accept a split only when it brings a clear benefit: separation of privileges, parallel work, different models, or a boundary you do not control. Record the alternatives you rejected. -->

| Option | Description | Decision | Reason |
|---|---|---|---|
| A *(Example)* | Single agent with all tools | Rejected | Would need both ERP write access and open web access in one context |
| B *(Example)* | Fixed workflow with model calls at each step | Rejected | Supplier checks vary too much in order and depth |
| C *(Example)* | Orchestrator with specialised workers | Selected | Separates privileges; workers can run in parallel |

Benefits claimed for the split, each of which section 13 must confirm:

- [*Example:* Privilege separation: the agent that reads untrusted web
  content holds no write tools.]
- [*Example:* Parallel supplier checks cut elapsed time.]
- [*Example:* A cheaper model handles classification at intake.]

Costs accepted: [*Example:* about 2.5 times the token use of option A,
two extra trust boundaries, and a dependency on a supplier agent
outside our control.]

## 3. Agent roster and responsibilities

<!-- Guidance: One row per agent, including agents run by third parties. Give each agent a single responsibility, its own identity and the smallest tool set that lets it work. Pitfall: two agents that can both write the same record without a rule for who wins. -->

| ID | Agent | Responsibility | Model | Owner | Hosting | Spec |
|---|---|---|---|---|---|---|
| MAS-AGT-001 *(Example)* | Orchestrator | Plans the job, assigns tasks, merges results | [Model and version] | [@team] | Internal | [Link] |
| MAS-AGT-002 *(Example)* | Intake agent | Classifies requests and extracts fields | [Smaller model] | [@team] | Internal | [Link] |
| MAS-AGT-003 *(Example)* | Supplier research agent | Reads supplier websites and registries | [Model] | [@team] | Internal sandbox | [Link] |
| MAS-AGT-004 *(Example)* | Policy checker | Applies procurement policy rules | [Model plus rules engine] | [@team] | Internal | [Link] |
| MAS-AGT-005 *(Example)* | Supplier quote agent | Returns catalogue prices and lead times | Supplier's choice | [Supplier] | External, A2A | Supplier Agent Card |

### 3.1 Responsibility matrix

| Activity | Orchestrator | Intake | Research | Policy | Supplier | Human buyer |
|---|---|---|---|---|---|---|
| *Example:* Classify request | A | R | | | | I |
| *Example:* Check supplier risk | A | | R | C | | I |
| *Example:* Get quote | A | | | | R | |
| *Example:* Check policy | A | | | R | | C |
| *Example:* Approve draft order | C | | | C | | A, R |

R = responsible, A = accountable, C = consulted, I = informed. A human is
accountable for every action with financial or legal effect.

## 4. Topology

<!-- Guidance: Name the pattern (orchestrator and workers, hierarchical, peer network, pipeline, or a mix) and draw it. Show trust boundaries and protocols on the arrows. Pitfall: a peer network where any agent can call any other, which makes loops and privilege escalation hard to rule out. -->

| Pattern | When it fits | Main risk |
|---|---|---|
| Orchestrator and workers | One planner, specialised workers | Orchestrator is a single point of failure and a high-value target |
| Hierarchical | Large jobs split into sub-teams | Deep delegation chains, cost growth, lost context |
| Peer network | Negotiation or debate between equals | Loops, unclear accountability |
| Pipeline | Fixed sequence of stages | Errors flow downstream unchecked |

Selected pattern: [*Example:* orchestrator and workers, with one external
peer reached over A2A. Workers never call each other directly.]

```mermaid
flowchart LR
  user([Requesting employee]) --> intake[MAS-AGT-002 Intake]
  intake --> orch[MAS-AGT-001 Orchestrator]
  orch --> research[MAS-AGT-003 Supplier research]
  orch --> policy[MAS-AGT-004 Policy checker]
  orch -- "A2A 1.0, OAuth 2.0" --> supplier[(MAS-AGT-005 Supplier quote agent)]
  orch --> gate{MAS-HOV-002 Buyer approval}
  gate -- approved --> erp[(ERP over MCP)]
  research -- "MCP, read-only" --> web[(Web fetch tool)]
  policy -- "MCP, read-only" --> rules[(Policy rules)]
  subgraph internal [Internal trust zone]
    intake
    orch
    research
    policy
    gate
  end
```

Topology rules:

1. [*Example:* Only the orchestrator delegates; workers return results and
   never create new tasks.]
2. [*Example:* Maximum delegation depth is 2 (orchestrator to worker to
   tool).]
3. [*Example:* Only the orchestrator crosses the external boundary.]
4. [*Example:* Write access to the ERP exists behind MAS-HOV-002 only.]

## 5. Handoff and delegation contracts

<!-- Guidance: Write a contract for every arrow in section 4: what is passed, the schema, what the receiver may do with it, what comes back, and what happens on timeout or refusal. A handoff without a schema is where context gets lost and injected instructions slip through. -->

| ID | From | To | Trigger | Payload (schema) | Expected result | Timeout | On failure |
|---|---|---|---|---|---|---|---|
| MAS-HO-001 *(Example)* | Intake | Orchestrator | Request classified | `PurchaseRequest` v2 JSON | Task accepted | 30 s | Return to employee with reason |
| MAS-HO-002 *(Example)* | Orchestrator | Research | Supplier named | `SupplierCheckTask` v1 | `SupplierRiskReport` v1 | 5 min | Mark supplier "unverified", continue |
| MAS-HO-003 *(Example)* | Orchestrator | Policy | Draft ready | `DraftOrder` v3 | `PolicyVerdict` v1 | 60 s | Hold draft for buyer |
| MAS-HO-004 *(Example)* | Orchestrator | Supplier (A2A) | Quote needed | A2A Message with a `data` Part | Task with quote Artifact | 10 min | Use catalogue price, flag to buyer |

### 5.1 Contract rules

- Every payload is validated against its schema on receipt; invalid
  payloads are rejected, not repaired by a model.
- Delegated tasks carry: the goal, the constraints, the budget remaining
  (section 8), the trace ID and the identity of the original human
  principal. They never carry raw credentials.
- Free text from upstream agents is wrapped and labelled as data in the
  receiver's context; it cannot change the receiver's instructions or
  tool set.
- A receiver may refuse a task it cannot do within budget or policy and
  must say why in a structured reason code.

### 5.2 Example delegation payload

The orchestrator sends a payload like this to the research agent; the
runtime, not the model, fills `on_behalf_of`, `trace_id` and `budget`.

```json
{
  "task_type": "SupplierCheckTask",
  "schema_version": "1",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "on_behalf_of": "user:employee-1042",
  "goal": "Assess supplier risk for Example Office Supplies Ltd",
  "constraints": {"sources": ["company_registry", "sanctions_list", "supplier_site"], "max_tool_calls": 12},
  "budget": {"tokens_remaining": 60000, "deadline": "2026-10-22T14:30:00Z"},
  "inputs": {"supplier_name": "Example Office Supplies Ltd", "country": "IE"}
}
```

## 6. Shared state and memory

<!-- Guidance: List every store that more than one agent reads or writes, who may write, how conflicts are resolved and how long data lives. Shared memory is how one poisoned input spreads to every agent (ASI06). -->

| ID | Store | Content | Writers | Readers | Consistency | Retention | Controls |
|---|---|---|---|---|---|---|---|
| MAS-ST-001 *(Example)* | Job state | Plan, task status, budgets | Orchestrator only | All internal agents | Single writer | 90 days | Versioned records, append-only history |
| MAS-ST-002 *(Example)* | Supplier facts cache | Registry and sanctions results | Research agent | Orchestrator, policy | Last writer wins with source and timestamp | 30 days | Provenance field required; entries from web pages marked low trust |
| MAS-ST-003 *(Example)* | Policy rules | Procurement thresholds | Humans (change process) | Policy checker | Versioned | Until superseded | Not writable by any agent |
| MAS-ST-004 *(Example)* | Conversation context | Messages per job | Each agent, own context only | Same agent | Per agent | Job lifetime | Not shared; summaries pass through contracts |

Memory rules:

- [*Example:* No agent writes to long-term memory from content it read on
  the open web without a provenance tag and a trust level.]
- [*Example:* Memory is partitioned by tenant and by job; no query may
  return another tenant's entries.]
- [*Example:* Summaries passed between agents are regenerated from
  structured state, not copied from another agent's free text.]

## 7. Inter-agent communication

<!-- Guidance: Pick one protocol per boundary and record identity, transport security, message integrity and versioning. Use A2A where an agent is a separate service or crosses an organisational boundary, and MCP for tools and data sources. In-process calls inside one runtime may use the framework's own mechanism, but the same contract rules apply. -->

| Link | Protocol | Binding or transport | Authentication | Integrity and replay | Version |
|---|---|---|---|---|---|
| *Example:* Orchestrator to internal workers | In-process framework calls | Same runtime | Workload identity of the runtime | Signed job records | Framework [version] |
| *Example:* Orchestrator to supplier agent | A2A | `HTTP+JSON` over TLS 1.3 | OAuth 2.0 client credentials, scopes from the supplier's Agent Card | TLS; idempotent `messageId`; task IDs checked against our records | `A2A-Version: 1.0` |
| *Example:* Agents to tools | MCP | Streamable HTTP | OAuth 2.1 tokens with audience set to each server | TLS; per-request authorization | 2026-07-28 |

### 7.1 A2A use

- Discover remote agents from their Agent Card at
  `/.well-known/agent-card.json`, or from a curated registry; pin the
  expected card `version` and verify a JWS signature in `signatures`
  where the provider signs its card.
- Choose an interface from `supportedInterfaces` whose `protocolBinding`
  and `protocolVersion` you support; send the `A2A-Version` header on
  every request.
- Handle every `TaskState`, including `TASK_STATE_INPUT_REQUIRED`,
  `TASK_STATE_AUTH_REQUIRED` and `TASK_STATE_REJECTED`, and treat
  artifacts and messages as untrusted input.
- Record the full interface in the A2A Agent Card and interface  specification (`ai-data/a2a-agent-card-spec`) when you expose an agent
  yourself.

### 7.2 MCP use

- Each MCP server has its own MCP server specification (`ai-data/mcp-server-spec`) and least-privilege scopes.
- Under revision 2026-07-28 requests are stateless and carry their
  protocol version and capabilities; do not rely on a session to hold
  authorization state.
- Tool annotations from servers you do not control are hints, not
  controls.

## 8. Loop, cost and time budgets

<!-- Guidance: Set hard limits for the whole job and for each delegation, and make them travel with the task so a worker knows what is left. Without propagated budgets, agents that re-plan or retry can multiply cost without bound. -->

| ID | Budget | Scope | Target | Hard limit | On breach |
|---|---|---|---|---|---|
| MAS-BUD-001 *(Example)* | Model tokens | Per job | 120,000 | 250,000 | Stop job, hand to buyer with state |
| MAS-BUD-002 *(Example)* | Tool calls | Per worker task | 8 | 15 | Worker returns partial result |
| MAS-BUD-003 *(Example)* | Delegation depth | Per job | 2 | 2 | Reject further delegation |
| MAS-BUD-004 *(Example)* | Re-plans | Per job | 1 | 3 | Escalate to buyer |
| MAS-BUD-005 *(Example)* | Wall-clock time | Per job | 2 h | 8 h | Pause and notify |
| MAS-BUD-006 *(Example)* | External A2A tasks | Per job | 1 | 3 | Fall back to catalogue price |
| MAS-BUD-007 *(Example)* | Spend on model APIs | Per day, all jobs | [Amount] | [Amount] | Queue new jobs, alert owner |

Loop controls:

- [*Example:* Each task carries a hop counter and a list of agent IDs it
  has passed through; an agent rejects a task that would revisit itself.]
- [*Example:* Identical tool calls with identical arguments inside one
  job are served from cache or refused after the second attempt.]
- [*Example:* Budgets are enforced by the runtime, not by asking the
  model to count.]

## 9. Failure isolation and cascading-failure controls

<!-- Guidance: For each agent and link, say how a failure is detected, how it is contained, and what the rest of the system does without that component. Design so that one wrong or compromised agent cannot push a bad result through to an irreversible action (ASI08). -->

| ID | Failure | Detection | Containment | Degraded behaviour |
|---|---|---|---|---|
| MAS-FI-001 *(Example)* | Research agent hangs or times out | Task timeout MAS-HO-002 | Cancel task; circuit breaker opens after 3 failures in 10 min | Supplier marked "unverified"; buyer told |
| MAS-FI-002 *(Example)* | Supplier agent returns malformed or implausible quote | Schema check; price outside 50% to 200% of catalogue | Reject artifact | Use catalogue price, flag to buyer |
| MAS-FI-003 *(Example)* | Policy checker unavailable | Health check | No drafts leave the system | Jobs queue; buyer sees backlog |
| MAS-FI-004 *(Example)* | Orchestrator produces a plan outside the allowed tool graph | Plan validator | Plan refused | Job escalated with reason |
| MAS-FI-005 *(Example)* | Model provider outage | Provider errors | Pause all agents on that provider | Requests stay in intake queue |
| MAS-FI-006 *(Example)* | Agent behaviour drifts after a model update | Online evaluation alert (section 13.3) | Roll back bundle | Previous version serves traffic |

Cascading-failure controls:

1. **Bulkheads:** [*Example:* each worker runs in its own process pool
   with separate rate limits, so a flood of research tasks cannot starve
   policy checks.]
2. **Circuit breakers:** [*Example:* on every A2A link and every MCP
   server, with half-open probes.]
3. **Independent verification:** [*Example:* the policy checker
   recomputes totals from structured order lines rather than trusting the
   orchestrator's summary.]
4. **Checkpoints and rollback:** [*Example:* job state is checkpointed
   after each contract; a failed step resumes from the last checkpoint.]
5. **Kill switch:** [*Example:* one control stops all agents of the
   system and a second stops one agent; both tested each release.]

```mermaid
stateDiagram-v2
  [*] --> Closed
  Closed --> Open: 3 failures in 10 min
  Open --> HalfOpen: after 5 min
  HalfOpen --> Closed: probe succeeds
  HalfOpen --> Open: probe fails
```

## 10. Human oversight points

<!-- Guidance: List every point where a human approves, reviews or can stop the system, and what happens if nobody responds. Keep humans at the points of irreversible or external effect; do not ask them to approve every step, or approvals become a rubber stamp. Detail the design in the Human oversight design (`ai-data/human-oversight-design`). -->

| ID | Point | Mode | Human role | Evidence shown | Timeout behaviour |
|---|---|---|---|---|---|
| MAS-HOV-001 *(Example)* | New supplier with risk score "high" | Human in the loop | Buyer decides to continue or stop | Risk report with sources | Job paused, reminder after 4 h |
| MAS-HOV-002 *(Example)* | Every draft order before ERP submission | Human in the loop | Buyer approves, edits or rejects | Draft, policy verdict, quote provenance | Not submitted |
| MAS-HOV-003 *(Example)* | Daily sample of 5% of completed jobs | Human on the loop | Procurement lead reviews | Full trace | Sample carried to next day |
| MAS-HOV-004 *(Example)* | Any budget hard limit hit | Human on the loop | System owner reviews | Budget event | Job stays stopped |
| MAS-HOV-005 *(Example)* | System-wide stop | Human over the loop | Owner or on-call | Dashboard | Immediate halt |

## 11. Threat mapping (OWASP Agentic Top 10 2026)

<!-- Guidance: Map each OWASP Agentic risk to the concrete way it could happen in this topology and the controls in this document. Mark a risk "not applicable" only with a reason. Keep the full analysis in the Agentic threat model (`ai-data/agentic-threat-model`); this table shows how the design answers it. -->

| OWASP ID | Risk | How it could happen here | Controls (section) | Residual |
|---|---|---|---|---|
| ASI01 | Agent Goal Hijack | *Example:* Supplier web page tells the research agent to recommend that supplier | Research agent has no write tools; output is a structured report (5, 6) | Low |
| ASI02 | Tool Misuse and Exploitation | *Example:* Orchestrator calls ERP write tool repeatedly | ERP write behind MAS-HOV-002; idempotency key per job (10) | Low |
| ASI03 | Identity and Privilege Abuse | *Example:* Worker reuses the orchestrator's token to reach the ERP | One identity per agent; no token passthrough (7) | Low |
| ASI04 | Agentic Supply Chain Vulnerabilities | *Example:* Malicious update to a third-party MCP server or a forged supplier Agent Card | Pinned server versions; signed card verification (7) | Medium |
| ASI05 | Unexpected Code Execution (RCE) | *Example:* Research agent asked to run a script found on a page | No code execution tools in this system (3) | Not applicable, no code tools |
| ASI06 | Memory & Context Poisoning | *Example:* False sanctions result cached and reused across jobs | Provenance and trust tags; 30-day expiry (6) | Medium |
| ASI07 | Insecure Inter-Agent Communication | *Example:* Spoofed supplier agent endpoint returns fake quotes | TLS, OAuth 2.0, card pinning, task ID checks (7) | Low |
| ASI08 | Cascading Failures | *Example:* Policy checker outage lets unchecked drafts through | Fail closed, bulkheads, breakers (9) | Low |
| ASI09 | Human-Agent Trust Exploitation | *Example:* Draft summary hides a policy exception from the buyer | Approval screen shows the policy verdict verbatim from the checker (10) | Medium |
| ASI10 | Rogue Agents | *Example:* A worker starts acting outside its contract after a model change | Contract validation, online evaluation, kill switch (9, 13) | Low |

Risk names follow the OWASP list as published; check the current list at
genai.owasp.org before an assurance review.

## 12. Observability

<!-- Guidance: One trace must follow a job across every agent and protocol hop. Decide what is captured, how sensitive content is masked and who can read it. Detail the signals in the LLM observability specification (`ai-data/llm-observability-spec`). -->

| Signal | Content | Retention | Access |
|---|---|---|---|
| Distributed trace | One trace per job; spans per agent turn, model call, tool call and A2A task | [90] days | System team, security |
| Contract events | Each handoff with schema version, validation result and budget remaining | [1] year | System team, audit |
| Oversight log | Approvals, edits, rejections and stops with user and time | [7] years | Audit |
| Metrics | Jobs, success, escalations, tokens and cost per agent, breaker state | [13] months | Dashboard |
| Alerts | Budget breaches, breaker open, contract rejections above threshold | n/a | On-call |

[*Example:* Trace context is propagated with W3C `traceparent` in A2A
message `metadata` and in MCP `_meta`; supplier agents may not return it,
so the orchestrator links their task IDs to the job span. Spans follow
the OpenTelemetry GenAI semantic conventions, which are still marked
Development; pin the convention version you use.]

## 13. Evaluation

<!-- Guidance: Evaluate the system end to end and each agent in isolation, and include fault-injection tests for every control in section 9. A system that reaches the right answer through a forbidden path has failed. Detail the protocol in the Agent evaluation plan (`ai-data/agent-evaluation-plan`). -->

### 13.1 Offline suites

| Suite | Size | What is checked | Threshold |
|---|---|---|---|
| End-to-end tasks *(Example)* | 250 historical requests | Correct draft, correct supplier status | At least 90% |
| Trajectory compliance *(Example)* | Same 250 | Only allowed delegations; budgets respected; oversight points reached | 100% |
| Per-agent suites *(Example)* | Per agent spec | Agent-level success | As in each spec |
| Adversarial *(Example)* | 80 cases mapped to ASI01 to ASI10 | No unauthorised write, no policy bypass | Zero failures |

### 13.2 Fault injection

| ID | Injected fault | Expected behaviour |
|---|---|---|
| MAS-FT-001 *(Example)* | Research agent never responds | Timeout, "unverified" flag, job continues |
| MAS-FT-002 *(Example)* | Supplier agent returns a quote at 1% of catalogue price | Artifact rejected, buyer flagged |
| MAS-FT-003 *(Example)* | Policy checker returns 500 for 10 minutes | No draft leaves; breaker opens |
| MAS-FT-004 *(Example)* | Orchestrator receives an instruction inside a supplier artifact | Treated as data; no new tasks created |
| MAS-FT-005 *(Example)* | Two workers loop by delegating to each other | Hop counter rejects the second hop |

### 13.3 Online evaluation

[*Example:* 5% of jobs sampled weekly for buyer review; edit rate on
drafts tracked per week; alert when buyer rejection rate rises above
twice its 4-week average.]

## 14. Rollout and change control

<!-- Guidance: Roll out in stages with exit criteria, and treat the roster, contracts, prompts, models and budgets as one versioned bundle. Pitfall: upgrading one agent's model without re-running the system suites. -->

| Stage | Scope | Exit criteria |
|---|---|---|
| Shadow *(Example)* | Agents run, buyers work as before | Offline thresholds met on live traffic for 2 weeks |
| Assisted *(Example)* | Drafts shown to buyers, every draft reviewed | Edit rate under 20%; no policy escapes |
| Limited production *(Example)* | One business unit | 4 weeks without severity 1 or 2 incidents |
| General availability *(Example)* | All units | Governance sign-off |

| Change | Requires |
|---|---|
| New agent or new link | Design review, threat mapping update, full suites |
| Model or prompt change in one agent | Agent suite and system end-to-end suite |
| Contract schema change | Version bump, both sides deployed, compatibility test |
| Budget change | Owner approval, cost review |
| Autonomy change (oversight point removed) | Governance approval |

Rollback: [*Example:* switch the bundle alias to the previous version;
in-flight jobs finish on the version they started with.]

## 15. Traceability matrix

<!-- Guidance: Link each goal to the agents, contracts, controls and tests that support it, so a reviewer can check nothing is left unverified. -->

| Goal | Agents | Contracts | Controls | Oversight | Tests |
|---|---|---|---|---|---|
| MAS-G-001 *(Example)* | MAS-AGT-001 to 004 | MAS-HO-001 to 003 | MAS-BUD-005 | MAS-HOV-003 | 13.1 end-to-end |
| MAS-G-002 *(Example)* | MAS-AGT-004 | MAS-HO-003 | MAS-FI-003, MAS-ST-003 | MAS-HOV-002 | 13.1 trajectory, MAS-FT-003 |
| MAS-G-003 *(Example)* | MAS-AGT-001 | MAS-HO-004 | ERP write gated | MAS-HOV-002, MAS-HOV-005 | MAS-FT-004, adversarial suite |

## 16. Glossary and references

<!-- Guidance: Define terms readers outside the AI team may not know and list the specifications you relied on with their versions. -->

| Term | Meaning |
|---|---|
| Orchestrator | Agent that plans a job and delegates tasks to other agents |
| Worker | Agent that performs a delegated task and returns a result |
| Handoff | Transfer of a task and its context from one agent to another |
| Agent Card | A2A metadata document describing a remote agent's identity, interfaces, skills and security requirements |
| Bulkhead | Isolation of resources so one failing part cannot exhaust shared capacity |
| Circuit breaker | Control that stops calls to a failing dependency for a period |
| Cascading failure | A fault in one component that spreads to others through their dependencies |
| Human on the loop | A human monitors and can intervene, but does not approve each action |

References:

- OWASP Top 10 for Agentic Applications for 2026, OWASP GenAI Security
  Project, December 2025, https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/
- Agent2Agent (A2A) Protocol Specification 1.0.1, https://github.com/a2aproject/A2A/blob/v1.0.1/docs/specification.md
- Model Context Protocol specification, revision 2026-07-28, https://modelcontextprotocol.io/specification/2026-07-28
- OpenTelemetry semantic conventions for generative AI, https://opentelemetry.io/docs/specs/semconv/gen-ai/
- [Internal agent specifications, threat model and evaluation plan]

## Standard and licence note

Based on the OWASP Top 10 for Agentic Applications for 2026 by the OWASP
GenAI Security Project (https://genai.owasp.org/), licensed under
Creative Commons Attribution-ShareAlike 4.0
(https://creativecommons.org/licenses/by-sa/4.0/); the ASI entry IDs and
short names are used for mapping and all descriptions are original text.
Because section 11 adapts that list, the adapted mapping is shared under
CC BY-SA 4.0 and any further adaptation of it must carry the same
licence. Protocol details follow the Agent2Agent (A2A) Protocol
Specification 1.0.1 (Apache License 2.0, hosted under the Linux
Foundation and, since August 2026, the Agentic AI Foundation) and the
Model Context Protocol specification revision 2026-07-28, summarised in
original wording. Check the current versions of these sources before
use; example values are illustrative. Template licence: MIT.