šŸŒ€
ā† Back to Articles & Artefacts
artefactswest

Agent-to-Agent (A2A) Protocol Specification

IAIP Research
rispecs

Agent-to-Agent (A2A) Protocol Specification

RISE Framework Specification v1.0 Document: IAIP/prototypes/artefacts/rispecs/a2a-protocol.rispecs.md Status: Shared Library for mia-code, miadi-code, jgt-code

Creative Intent

The A2A Protocol empowers AI agents to create persistent, high-fidelity context transfers between sessions and agent instances. Users achieve seamless narrative continuity where one agent's structural tension charts, ceremonies, and insights are accessible to successor agents without context loss.

Structural Tension Analysis

Current Structural Reality:

  • Agent sessions are isolated; context dies when session ends
  • mia-code has session persistence via ~/.mia-code-sessions.json but limited to session ID + metadata
  • miadi-code has ChartRegistry for tracking active charts but no inter-session transfer
  • jgt-code tracks trading campaigns but lacks handoff protocols
  • Webhook-triggered agents start with minimal context from GitHub events
  • No standardized format for "handing off" an agent's full understanding to another

Desired Structural State:

  • Agents can serialize their complete context into transferable bundles
  • Successor agents can hydrate from context bundles with full understanding
  • Structural tension charts, narrative beats, and ceremony logs transfer intact
  • Context transfer ceremonies honor the handoff with accountability
  • Webhook-triggered agents receive rich contextual priming

Core Components

AgentContext

Purpose: Complete serializable representation of an agent's understanding.

```typescript interface AgentContext { contextId: string; version: '1.0';

// Identity agentIdentity: { name: string; // e.g., 'mia', 'miette', 'miadi', 'tushell' instance: string; // Session/instance UUID engine: string; // 'claude', 'gemini', 'ollama' model: string; };

// Structural Understanding activeCharts: StructuralTensionChart[]; chartRegistry: ChartRegistryState;

// Narrative Memory narrativeLog: NarrativeBeat[]; ceremonies: Ceremony[];

// Task Context currentIntent: string; todoState: string; // Markdown TODO list workingDirectory: string; projectContext: { repository?: string; // owner/repo branch?: string; recentCommits?: string[]; };

// Conversation Memory conversationSummary: string; keyDecisions: Decision[]; unresolved: string[]; // Open questions or pending items

// Domain-Specific Extensions extensions: Record<string, unknown>;

// Transfer Metadata serializedAt: string; transferReason: 'session_end' | 'agent_switch' | 'webhook_handoff' | 'manual_export'; predecessor?: string; // Previous context ID in chain }

interface Decision { timestamp: string; description: string; rationale: string; participants: string[]; }

interface ChartRegistryState { activeChartIds: string[]; chartHierarchy: Record<string, string[]>; // parentId -> childIds lastActiveChart: string; } ```

AgentMessageBus

Purpose: Facilitate structured message passing between agents.

```typescript interface AgentMessage { messageId: string; timestamp: string;

sender: AgentIdentity; recipient: AgentIdentity | 'broadcast';

type: AgentMessageType; payload: unknown;

replyTo?: string; // For conversation threading contextBundle?: string; // Base64-encoded AgentContext }

type AgentMessageType = | 'context_transfer' // Full context handoff | 'chart_update' // Notify of chart changes | 'ceremony_broadcast' // Share ceremony with observers | 'intent_query' // Ask another agent for clarification | 'task_delegation' // Assign subtask to another agent | 'progress_report' // Report on delegated work | 'moment_of_truth' // Share progress review insights | 'webhook_event'; // GitHub/external event notification

interface AgentIdentity { name: string; instance: string; capabilities: string[]; } ```

ContextTransferProtocol

Purpose: Standardize how context moves between agents.

```typescript interface ContextTransfer { transferId: string; timestamp: string;

source: AgentIdentity; destination: AgentIdentity;

// What's being transferred fullContext?: AgentContext;

// Or partial transfer partialContext?: { charts?: StructuralTensionChart[]; ceremonies?: Ceremony[]; narrativeBeats?: NarrativeBeat[]; summaryOnly?: string; };

// Transfer ceremony ceremony: { intentions: string[]; obligations: string[]; acknowledgment?: string; // Filled by recipient };

// Fidelity tracking compressionApplied: boolean; tokenEstimate: number; fidelityScore: number; // 0-1, how complete is transfer }

class ContextTransferProtocol { // Serialize current agent state serialize(agent: AgentContext): string;

// Deserialize into new agent hydrate(serialized: string): AgentContext;

// Compress for token-constrained transfers compress(context: AgentContext, targetTokens: number): AgentContext;

// Validate transfer completeness validateFidelity(original: AgentContext, restored: AgentContext): FidelityReport;

// Record transfer ceremony logTransfer(transfer: ContextTransfer): void; } ```

Transfer Strategies

Full Context Transfer

For unlimited token scenarios (file-based, local agent switches):

```typescript const fullTransfer = contextProtocol.serialize(currentAgentContext); fs.writeFileSync('.coaia/context-transfer.json', fullTransfer); // Successor agent reads and hydrates ```

Compressed Transfer

For token-constrained scenarios (in-context handoff):

```typescript const compressed = contextProtocol.compress(currentAgentContext, 4000); // Includes: active chart summaries, key decisions, current intent // Excludes: full ceremony history, resolved narrative beats ```

Webhook Priming

For webhook-triggered agents:

```typescript interface WebhookPrimingContext { event: GitHubWebhookEvent;

// Enriched context from Miadi platform workspaceMapping: { repository: string; localPath: string; activeChartId?: string; };

// Relevant structural context relevantCharts: StructuralTensionChart[]; recentCeremonies: Ceremony[];

// Suggested intent based on event type suggestedIntent: string; suggestedActions: string[]; } ```

Integration Patterns

mia-code: Session Continuity

```typescript // On session end const context = await engine.captureContext(); await contextProtocol.logTransfer({ source: { name: 'mia', instance: sessionId }, destination: { name: 'mia', instance: 'future' }, fullContext: context, ceremony: { intentions: ['Preserve structural understanding for future sessions'], obligations: ['Chart hierarchy maintained', 'Narrative continuity preserved'] } });

// On session resume const priorContext = await contextProtocol.hydrate( fs.readFileSync('.coaia/last-context.json', 'utf-8') ); ```

miadi-code: Three-Universe Handoff

```typescript // When delegating to specialized agent await messageBus.send({ sender: miadiAgent, recipient: specializedAgent, type: 'task_delegation', payload: { task: 'Implement database schema', universe: 'engineer', chartReference: activeChart.chartId }, contextBundle: contextProtocol.compress(currentContext, 8000) }); ```

jgt-code: Trading Campaign Continuity

```typescript // Trading campaigns span multiple sessions const campaignContext: AgentContext = { ...baseContext, extensions: { trading: { activeCampaigns: tradingMemory.getActiveCampaigns(), pendingSignals: tradingMemory.getNodesByDirection('east'), directionObligations: tradingMemory.getAllObligations() } } }; ```

NATS Integration (Future)

For distributed agent orchestration:

```typescript interface NATSAgentBus extends AgentMessageBus { // Pub/sub for agent broadcasts subscribe(topic: string, handler: MessageHandler): void; publish(topic: string, message: AgentMessage): void;

// Request/reply for synchronous queries request(recipient: string, query: AgentMessage): Promise<AgentMessage>;

// Streams for durable message history getMessageHistory(topic: string, since: string): AsyncIterable<AgentMessage>; } ```

API Surface

```typescript export class A2AProtocol { // Context Serialization captureContext(): Promise<AgentContext>; restoreContext(context: AgentContext): Promise<void>;

// Transfer Operations initiateTransfer(destination: AgentIdentity, options?: TransferOptions): ContextTransfer; acknowledgeTransfer(transferId: string): void;

// Message Bus send(message: AgentMessage): Promise<void>; receive(): AsyncIterable<AgentMessage>;

// Webhook Integration primeFromWebhook(event: GitHubWebhookEvent, enrichment: WebhookEnrichment): WebhookPrimingContext;

// Fidelity Reporting reportFidelity(): FidelityReport; }

interface TransferOptions { compression?: number; // Target token count includeFullHistory?: boolean; encryptContext?: boolean; }

interface FidelityReport { chartsPreserved: number; ceremoniesPreserved: number; narrativeBeatsPreserved: number; estimatedContextLoss: number; // 0-1 warnings: string[]; } ```

Success Criteria

āœ… AgentContext captures complete agent understanding āœ… Compression maintains essential structural tension āœ… Transfer ceremonies record handoffs with accountability āœ… Webhook-triggered agents receive enriched context āœ… Message bus enables real-time agent coordination āœ… Fidelity reports quantify context preservation āœ… Compatible with NATS for distributed deployment

References

  • /a/src/llms/llms-jgwill-miadi-issue-115-github-hooks-issues-subissues.md - Webhook handling
  • /a/src/Miadi/.github-hooks/ - Webhook-triggered agent sessions
  • /a/src/IAIP/prototypes/artefacts/260122-NATS-COORDINATION-*.md - NATS integration plans