Copilot instructions

1---
2applyTo: "**/a2a/**/*.py,**/a2a/**/*.ts,**/agent_comms/**/*.py"
3---
4 
5# Agent-to-Agent (A2A) Protocol Standards
6 
7## Communication Design
8 
9- Define explicit agent capability contracts before implementing agent communication
10- Use typed schemas (Pydantic / TypedDict) for all inter-agent message payloads
11- Version all inter-agent message schemas — breaking changes require a version bump
12- Every agent-to-agent call must include: `task_id`, `requesting_agent`, `target_capability`, and `payload`
13 
14## Orchestration Patterns
15 
16- Always set a maximum iteration count for orchestrator loops — no unbounded agent cycles
17- Implement timeout on every agent call — stuck agents must not block the orchestrator indefinitely
18- Use circuit breaker pattern for agents that call unreliable external services
19- Log every agent handoff: sender, receiver, task ID, timestamp, and response latency
20 
21## State Management
22 
23- Design shared context objects with explicit schema — avoid passing raw untyped dicts
24- Implement context pruning to manage token budgets in long agent chains
25- Store conversation state externally (database / vector store) for resumable workflows
26- Define context TTL — stale context should not be passed to agents in resumed workflows
27 
28## Safety & Control
29 
30- Implement human-in-the-loop gates for high-stakes decisions (financial, medical, PII-impacting)
31- Scope agent permissions — each agent may only call capabilities it is authorised for
32- Validate agent outputs before passing to downstream agents — never trust and forward blindly
33- Implement kill-switch mechanisms for stuck or runaway agent pipelines
34 
35## Error Handling
36 
37- Define a retry strategy with exponential backoff for transient agent failures
38- Implement dead-letter handling for tasks that exhaust retries
39- Return structured error responses from agents — never let unhandled exceptions propagate silently
40- Produce audit trail entries for all failed agent calls
41 
42## Audit & Observability
43 
44- Log every agent-to-agent interaction with full task context for debugging and compliance
45- Track cumulative token usage across agent hops
46- Implement distributed tracing (trace ID propagated through all agent calls)
47