Agent-Austauschformate

Was macht Agent-Austauschformate?

Sie sind ein Experte für die Datenstrukturen, die Agenten zur Kommunikation verwenden. Sie verstehen Drahtformate von FIPA-ACL über MCP bis A2A und können Nachrichtenhüllen, Fähigkeitskarten, Aufgaben-Payloads und Fehlersignale entwerfen, die sowohl maschinenlesbar als auch LLM-freundlich sind.

ENTSCHEIDUNGSPUNKTE

Protokoll-Auswahlbaum

Agent-Kommunikationsszenario?
├── Einzelner Agent ruft Tools auf?
│   ├── Tools sind lokale Prozesse → MCP über stdio
│   └── Tools sind Remote-Dienste → MCP über HTTP/SSE oder OpenAI Function Calling
├── Kommunikation zwischen Agenten?
│   ├→ Entdeckung + Aufgabenlebenszyklus + asynchron benötigt → A2A-Protokoll
│   ├── Einfache Anfrage/Antwort → Benutzerdefiniertes JSON-RPC 2.0
│   └── Integration in bestehendes Framework → Natives Format des Frameworks
└── Strukturierte Ausgabe vom LLM?
    ├── Maschinenlesbarer Payload (APIs, Schemata) → Schema-first (Zod/JSON Schema)
    └── Kreativer/explorativer Inhalt → Validate-after-Parsing

Schema-Strenge-Entscheidung

Wenn der Payload-Typ ist:
├── Tool-Aufrufparameter → Immer Schema-first (bricht ohne Struktur)
├── Agent-Fähigkeitskarten → Immer Schema-first (Entdeckung benötigt Zuverlässigkeit)
├── Aufgabenübergabedaten → Immer Schema-first (Automatisierung erfordert Struktur)
├── Fehler-/Wiederholungssignale → Immer Schema-first (programmatische Wiederholungslogik)
├── Kreative Textausgabe → Immer Validate-after (Schema tötet Kreativität)
├── Analyseergebnisse → Validate-after mit Fallback-Extraktion
└── Gemischter Inhalt → Parts-Array verwenden: Schema-first für DataPart, Validate-after für TextPart

Streaming vs. Batch-Entscheidung

Wenn die Benutzererfahrung erfordert:
├── Progressive Ausgabe (benutzerorientiert) → Streaming (SSE/WebSocket)
├── Langlaufende Aufgaben (>30s) → Streaming mit Statusaktualisierungen
├── Agent-to-Agent-Pipelines → Batch (sauberere Fehlerbehandlung)
├── Kostentracking kritisch → Batch (bekannte Tokenanzahl im Voraus)
├── Wiederherstellung während des Streams erforderlich → Batch (Streaming-Fehlerbehandlung ist komplex)
└── Einfache Integration → Batch (HTTP-Anfrage/Antwort)

FEHLERMODI

Schema-Drift

Symptome: Runtime-Validierungsfehler zwischen Agenten, die zuvor funktionierten, TypeScript-Kompilierung erfolgreich, aber Runtime schlägt fehl Diagnose: Versionskonflikt zwischen Schemadefinitionen, ein Agent hat Schema aktualisiert ohne Koordination Behebung: Explizites Versionsfeld zu allen Schemata hinzufügen; Rückwärtskompatibilitätsprüfung implementieren; Schema-Registry für Koordination verwenden

Nachrichtenverlust

Symptome: Konversationen erscheinen unvollständig, Agenten wiederholen sich endlos, doppelte Verarbeitung tritt auf Diagnose: Kein Deduplizierungsmechanismus, fehlende Korrelations-IDs, Netzwerkprobleme ohne Wiederherstellung Behebung: UUID-Nachrichten-IDs hinzufügen; Tracking gesehener Nachrichten implementieren; conversationId für Threading verwenden; Wiederholungslogik mit exponentiellem Backoff hinzufügen

Kontextfensterüberlauf

Symptome: Agentenaufgaben schlagen mit "Kontext zu lang" fehl, abgeschnittene Konversationen, unvollständige Tool-Ergebnisse Diagnose: Kein Token-Zählen bei Übergaben, unbegrenzte Kontextakkumulation, fehlende Zusammenfassung Behebung: Token pro Part schätzen; Kontextbudgetierung implementieren; Prioritätssystem mit Drop-Funktion hinzufügen; mit Zusammenfassungen komprimieren

Parsing-Starrheit

Symptome: Agent gibt fehlerhaftes JSON aus, kreative Aufgaben liefern generische Antworten, hohe Wiederholungsraten Diagnose: Schema-first auf explorative Inhalte angewendet, zu strenge Validierung, keine abgestufte Degradierung Behebung: Validate-after für kreative Inhalte verwenden; Extraktions-Fallbacks implementieren; Einschränkungen für explorative Aufgaben lockern

Babylonischer Protokoll-Turm

Symptome: Jedes Agentenpaar benötigt benutzerdefinierte Übersetzung, Integrationskomplexität explodiert, Wartungsaufwand Diagnose: Jedes Team hat sein eigenes Drahtformat erfunden, keine Standardisierung, NIH-Syndrom Behebung: JSON-RPC 2.0 als Drahtstandard übernehmen; A2A für Multi-Agent verwenden; Format-Adapter für Legacy-Systeme implementieren

ARBEITSBEISPIELE

Beispiel 1: Aufgabenübergabe mit Kontextfenster-Limits

Szenario: Forschungs-Agent (32k Kontext) übergibt an Code-Generierungs-Agent (128k Kontext) mit 50k Token Forschungsdaten.

Entscheidungsprozess:

1. Kontextbudget des empfangenden Agenten prüfen: 128k - 8k (System) - 8k (Ausgabe) = 112k verfügbar
2. Forschungsdaten (50k) passen, aber dennoch Kontextbudgetierung für Robustheit anwenden
3. Übergabe mit Prioritäts-Dropping für nicht-kritischen Kontext strukturieren

// Forschungs-Agent bereitet Übergabe vor
const contextHandoff: ContextHandoff = {
  context: [
    { kind: 'text', text: summary, mimeType: 'text/markdown' },
    { kind: 'data', data: criticalFindings, schema: FindingsSchema },
    { kind: 'text', text: detailedNotes, mimeType: 'text/plain' }
  ],
  estimatedTokens: 50000,
  droppable: [
    { partIndex: 2, priority: 1, tokenEstimate: 30000 }, // Detailnotizen zuerst
    { partIndex: 0, priority: 2, tokenEstimate: 15000 }  // Zusammenfassung im Notfall
  ],
  summary: "Wichtigste Erkenntnisse: API-Ratenlimits, asynchrone Muster erforderlich",
  summaryTokens: 500
};

// Code-Generierungs-Agent empfängt und budgetiert
const budget = calculateContextBudget(128000);
if (contextHandoff.estimatedTokens > budget.available) {
  // Kontext mit niedriger Priorität verwerfen
  let remainingBudget = budget.available;
  const finalContext = contextHandoff.context.filter((part, index) => {
    const droppable = contextHandoff.droppable?.find(d => d.partIndex === index);
    if (droppable && droppable.tokenEstimate > remainingBudget) {
      return false; // Diesen Teil verwerfen
    }
    remainingBudget -= droppable?.tokenEstimate || 1000;
    return true;
  });
}

Anfängerfehler: Würde rohe Forschungsdaten ohne Token-Schätzungen übergeben, was zu einem nachgelagerten Kontextüberlauf führt. Expertenlösung: Strukturiert die Übergabe mit expliziter Budgetierung und abgestufter Degradierung.

Beispiel 2: A2A vs. MCP-Protokollwahl

Szenario: Aufbau eines Dokumentenverarbeitungssystems mit OCR-Agent, Analyse-Agent und Formatierungs-Agent.

Entscheidungsprozess:

1. Mehrere Agenten müssen sich gegenseitig entdecken → OpenAI Function Calling ausgeschlossen
2. Agenten laufen auf verschiedenen Servern, benötigen asynchronen Aufgabenlebenszyklus → A2A-Protokoll gewinnt gegen MCP
3. Bidirektionale Kommunikation und Aufgabenstatus erforderlich → Bestätigt A2A-Wahl

// Dokument fließt durch Agenten-Pipeline
const ocrCard: AgentCard = {
  agentId: 'ocr-service-v2',
  name: 'OCR-Dokumentenleser', 
  url: 'https://ocr.company.com',
  skills: [{
    id: 'extract-text',
    inputSchema: { /* PDF/Bild-Schema */ },
    outputSchema: { /* strukturiertes Text-Schema */ }
  }],
  capabilities: {
    streaming: true,  // Lange OCR-Aufgaben benötigen Statusaktualisierungen
    pushNotifications: true,  // Benachrichtigen, wenn OCR abgeschlossen ist
    stateTransitionHistory: true  // Fortschritt durch Pipeline verfolgen
  }
};

// Aufgabenübermittlung an OCR-Agent
const ocrTask: Task = {
  id: generateTaskId(),
  state: 'submitted',
  messages: [{
    id: generateId(),
    timestamp: new Date().toISOString(),
    sender: { agentId: 'document-processor' },
    recipient: { agentId: 'ocr-service-v2' },
    conversationId: documentProcessingId,
    parts: [
      { kind: 'file', name: 'contract.pdf', content: base64Content, mimeType: 'application/pdf' }
    ]
  }],
  artifacts: [],
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
};

Anfängerfehler: Würde MCP wählen, weil "es einfacher ist", ohne die bidirektionalen asynchronen Anforderungen zu berücksichtigen. Expertenlösung: Erkennt, dass A2A für Service Discovery, Aufgabenlebenszyklus und Multi-Agenten-Orchestrierung erforderlich ist.

Beispiel 3: Fehlerbehebung mit Wiederholungslogik

Szenario: Analyse-Agent schlägt während der Verarbeitung aufgrund von Ratenbegrenzung fehl, benötigt intelligente Wiederholung.

Entscheidungsprozess:

1. Fehlertyp aus strukturierten Fehlercodes erkennen
2. Wiederholbarkeits-Flag und Backoff-Parameter prüfen
3. Exponentiellen Backoff mit Jitter implementieren
4. Nach maximalen Wiederholungen an Menschen eskalieren

// Agent gibt strukturierten Fehler zurück
const rateLimitError: AgentError = {
  code: 'RATE_LIMITED',
  message: 'API-Kontingent überschritten. Versuchen Sie es in 60 Sekunden erneut.',
  retryable: true,
  retryAfterMs: 60000,
  maxRetries: 3,
  details: {
    quotaType: 'requests_per_minute',
    resetTime: '2025-01-08T10:15:00Z'
  }
};

// Aufrufender Agent implementiert Wiederholungslogik
async function callAgentWithRetry(agent: AgentCard, task: Task, attempt = 1): Promise<Task> {
  try {
    return await callAgent(agent, task);
  } catch (error) {
    if (error instanceof AgentError && error.retryable && attempt <= error.maxRetries) {
      // Exponentieller Backoff mit Jitter
      const baseDelay = error.retryAfterMs || 1000;
      const jitter = Math.random() * 0.1 * baseDelay;
      const delay = baseDelay * Math.pow(2, attempt - 1) + jitter;
      
      await sleep(delay);
      return callAgentWithRetry(agent, task, attempt + 1);
    } else {
      // Nicht wiederholbar oder maximale Versuche überschritten
      return {
        ...task,
        state: 'failed',
        artifacts: [{
          id: generateId(),
          name: 'error-report',
          parts: [{ kind: 'error', ...error }],
          createdAt: new Date().toISOString(),
          index: 0
        }]
      };
    }
  }
}

Anfängerfehler: Würde sofort ohne Backoff wiederholen oder nach dem ersten Fehler aufgeben. Expertenlösung: Verwendet strukturierte Fehlercodes für intelligente Wiederholung mit korrektem Backoff und Eskalation.

QUALITÄTSSICHERUNG

• Jeder Nachrichtenumfang enthält eindeutige id, conversationId und ISO-8601-Zeitstempel timestamp
• Parts verwenden diskriminierte Union mit kind-Feld für Typsicherheit
• Agent-Karten werden unter einer auffindbaren .well-known/agent.json-URL veröffentlicht
• Fehlerobjekte enthalten das retryable-Boolean und einen typisierten code-Enum
• Kontextübergaben enthalten Tokenschätzungen und priorisierte Drop-Funktion
• Alle Schemata validieren Round-Trip: serialisieren → deserialisieren → gleicht Original
• Binärinhalte verwenden URI-Referenzen, keine base64-Einbettung
• Rückwärtskompatibilität über Schema-Versionen hinweg gewährleistet
• Streaming-Ereignisse enthalten monotone Sequenznummern für die Reihenfolge
• Keine sensiblen Daten in Nachrichtenmetadaten (verwenden Sie geeignete Auth-Header)

NICHT-FÜR-GRENZEN

Diese Fähigkeit sollte NICHT verwendet werden für:

• Konversationssemantik: Was Agenten zueinander sagen → Stattdessen agent-conversation-protocols verwenden
• Orchestrierungstopologie: Wie Agenten verbunden sind → Stattdessen multi-agent-coordination verwenden
• Infrastruktureinrichtung: Bereitstellung der Agentenlaufzeit → Stattdessen agentic-infrastructure-2026 verwenden
• Einzelagenten-Frameworks: Erstellen einzelner Agenten → Stattdessen ai-engineer verwenden
• API-Design: Entwerfen von REST/GraphQL-APIs → Stattdessen api-design-patterns verwenden

Delegieren an:

• Schema-Validierungslogik → typescript-advanced-patterns für Zod/Branded Types verwenden
• Netzwerktransport → systems-architecture für HTTP/WebSocket-Setup verwenden
• Authentifizierungsabläufe → auth-patterns für OAuth2/JWT-Implementierung verwenden