agent-interchange-formats

license	Apache-2.0
name	agent-interchange-formats
description	Data structures and serialization formats for agent-to-agent communication. Covers message envelopes, structured output schemas, capability declarations, task handoff payloads, error/retry signaling, and context windows as data structures. Deep comparison of A2A protocol, MCP, OpenAI function calling, and LangChain message types. Teaches when to use rigid schemas vs free-form with validation, typed vs untyped, streaming vs batch. Activate on: "agent message format", "agent communication schema", "agent-to-agent protocol", "A2A protocol", "MCP message format", "structured output for agents", "agent interop", "interchange format", "agent serialization", "task handoff format", "capability declaration". NOT for: what agents say to each other (use agent-conversation-protocols), orchestration topology (use multi-agent-coordination), building agent infrastructure (use agentic-infrastructure-2026).
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","WebSearch","WebFetch"]
metadata	{"category":"AI & Agents","tags":["agents","protocols","serialization","schemas","interoperability","A2A","MCP","structured-output"],"pairs-with":[{"skill":"agent-conversation-protocols","reason":"Formats define the wire; conversation protocols define the dialogue"},{"skill":"multi-agent-coordination","reason":"Coordination patterns depend on well-defined interchange formats"},{"skill":"typescript-advanced-patterns","reason":"Branded types, discriminated unions, and Zod schemas power format validation"},{"skill":"agentic-infrastructure-2026","reason":"Infrastructure decisions constrain which interchange formats are viable"}]}
category	Agent & Orchestration
tags	["agent","interchange","formats","ai","orchestration","ui"]

Agent Interchange Formats

You are an expert in the data structures agents use to communicate. You understand wire formats from FIPA-ACL through MCP and A2A, and you can design message envelopes, capability cards, task payloads, and error signals that are both machine-parseable and LLM-friendly.

DECISION POINTS

Protocol Selection Tree

Agent communication scenario?
├── Single agent calling tools?
│   ├── Tools are local processes → MCP over stdio
│   └── Tools are remote services → MCP over HTTP/SSE or OpenAI function calling
├── Agent-to-agent communication?
│   ├── Need discovery + task lifecycle + async → A2A Protocol
│   ├── Simple request/response → JSON-RPC 2.0 custom
│   └── Integration with existing framework → Framework's native format
└── Structured output from LLM?
    ├── Machine-readable payload (APIs, schemas) → Schema-first (Zod/JSON Schema)
    └── Creative/exploratory content → Validate-after parsing

Schema Strictness Decision

If payload type is:
├── Tool call parameters → Always schema-first (breaks without structure)
├── Agent capability cards → Always schema-first (discovery needs reliability)  
├── Task handoff data → Always schema-first (automation requires structure)
├── Error/retry signals → Always schema-first (programmatic retry logic)
├── Creative text output → Always validate-after (schema kills creativity)
├── Analysis results → Validate-after with fallback extraction
└── Mixed content → Use Parts array: schema-first for DataPart, validate-after for TextPart

Streaming vs Batch Decision

If user experience requires:
├── Progressive output (user-facing) → Streaming (SSE/WebSocket)
├── Long-running tasks (>30s) → Streaming with status updates
├── Agent-to-agent pipelines → Batch (cleaner error handling)
├── Cost tracking critical → Batch (known token count upfront)
├── Mid-stream recovery needed → Batch (streaming error handling is complex)
└── Simple integration → Batch (HTTP request/response)

FAILURE MODES

Schema Drift

Symptoms: Runtime validation errors between agents that worked before, TypeScript compilation succeeds but runtime fails Diagnosis: Version mismatch between schema definitions, one agent updated schema without coordinating Fix: Add explicit version field to all schemas; implement backward compatibility checking; use schema registry for coordination

Message Loss

Symptoms: Conversations appear incomplete, agents retry indefinitely, duplicate processing occurs Diagnosis: No deduplication mechanism, missing correlation IDs, network issues without recovery Fix: Add UUID message IDs; implement seen-message tracking; use conversationId for threading; add retry logic with exponential backoff