A2A JS SDK Komplettanleitung: Schnellstart-Guide

Inhaltsverzeichnis

Was ist das A2A JS SDK?
A2A JS Installation und Einrichtung
A2A JS Grundkonzepte
Erstellen Ihres ersten A2A JS Agenten
A2A JS Server-Entwicklung
A2A JS Client-Verwendung
A2A JS Erweiterte Funktionen
A2A JS Best Practices
A2A JS Fehlerbehebung

Was ist das A2A JS SDK?

Das A2A JS SDK ist eine leistungsstarke Bibliothek, die speziell für JavaScript/TypeScript-Entwickler entwickelt wurde, um intelligente Agentenanwendungen zu erstellen, die dem Agent2Agent (A2A) Protokoll entsprechen. Mit diesem A2A JS Framework können Entwickler leicht intelligente Agentensysteme erstellen, die miteinander kommunizieren und zusammenarbeiten können.

Hauptvorteile von A2A JS

🚀 Benutzerfreundlichkeit: A2A JS bietet eine intuitive API für schnellen Einstieg
🔄 Echtzeit-Kommunikation: Unterstützung für Streaming-Verarbeitung und Server-Sent Events (SSE)
🛡️ Typsicherheit: TypeScript-basiert, bietet vollständige Typunterstützung
🌐 Plattformübergreifend: A2A JS kann in Node.js- und Browser-Umgebungen ausgeführt werden
📡 Standardprotokoll: Vollständige Implementierung der A2A-Protokollspezifikation

A2A JS Installation und Einrichtung

A2A JS SDK Installation

Installieren Sie das A2A JS SDK mit npm:

npm install @a2a-js/sdk

Oder verwenden Sie yarn:

yarn add @a2a-js/sdk

Überprüfung der A2A JS Installation

Erstellen Sie eine einfache Testdatei, um die korrekte Installation von A2A JS zu überprüfen:

import { A2AClient, AgentCard } from "@a2a-js/sdk";

console.log("A2A JS SDK erfolgreich installiert!");

A2A JS Grundkonzepte

Bevor Sie mit A2A JS beginnen, ist es wichtig, die folgenden Grundkonzepte zu verstehen:

1. Agent-Karte

Jeder A2A JS Agent benötigt eine Agent-Karte, die seine Fähigkeiten und Schnittstelle beschreibt:

import { AgentCard } from "@a2a-js/sdk";

const agentCard: AgentCard = {
  name: 'Mein A2A JS Agent',
  description: 'Intelligenter Agent, erstellt mit dem A2A JS SDK',
  url: 'http://localhost:3000/',
  provider: {
    organization: 'A2A JS Entwickler',
    url: 'https://example.com'
  },
  version: '1.0.0',
  capabilities: {
    streaming: true,
    pushNotifications: false,
    stateTransitionHistory: true,
  },
  skills: [{
    id: 'general_chat',
    name: 'Allgemeiner Chat',
    description: 'Allgemeine Konversation mit A2A JS',
    tags: ['chat', 'a2a-js'],
    examples: ['Hallo', 'Hilfe bei der Beantwortung von Fragen']
  }]
};

2. Agent-Ausführer

Die Hauptausführungslogik von A2A JS wird über den AgentExecutor implementiert:

import { AgentExecutor, RequestContext, IExecutionEventBus } from "@a2a-js/sdk";

class MyA2AJSExecutor implements AgentExecutor {
  async execute(
    requestContext: RequestContext,
    eventBus: IExecutionEventBus
  ): Promise<void> {
    // A2A JS Agent-Logik
    console.log("A2A JS Agent verarbeitet Anfrage...");
  }

  async cancelTask(taskId: string, eventBus: IExecutionEventBus): Promise<void> {
    console.log(`A2A JS Aufgabe wird abgebrochen: ${taskId}`);
  }
}

Erstellen Ihres ersten A2A JS Agenten

Lassen Sie uns ein vollständiges Agenten-Beispiel mit dem A2A JS SDK erstellen:

Schritt 1: A2A JS Agent-Karte definieren

import { AgentCard } from "@a2a-js/sdk";

const myAgentCard: AgentCard = {
  name: 'Hello World A2A JS Agent',
  description: 'Mein erster A2A JS Agent zum Erlernen des SDKs',
  url: 'http://localhost:3000/',
  provider: {
    organization: 'A2A JS Tutorial',
    url: 'https://example.com'
  },
  version: '1.0.0',
  capabilities: {
    streaming: true,
    pushNotifications: false,
    stateTransitionHistory: true,
  },
  defaultInputModes: ['text/plain'],
  defaultOutputModes: ['text/plain'],
  skills: [{
    id: 'hello_world',
    name: 'Hello World',
    description: 'A2A JS Beispiel-Fähigkeit: Antworten auf Begrüßungen',
    tags: ['hello', 'greeting', 'a2a-js'],
    examples: [
      'Hallo',
      'Willkommen',
      'Erzähl mir von A2A JS'
    ],
    inputModes: ['text/plain'],
    outputModes: ['text/plain']
  }],
  supportsAuthenticatedExtendedCard: false,
};

Schritt 2: A2A JS Ausführer-Implementierung

import {
  AgentExecutor,
  RequestContext,
  IExecutionEventBus,
  Task,
  TaskState,
  TaskStatusUpdateEvent
} from "@a2a-js/sdk";
import { v4 as uuidv4 } from "uuid";

class HelloWorldA2AJSExecutor implements AgentExecutor {
  private cancelledTasks = new Set<string>();

  async cancelTask(taskId: string, eventBus: IExecutionEventBus): Promise<void> {
    this.cancelledTasks.add(taskId);
    console.log(`A2A JS Ausführer bricht Aufgabe ab: ${taskId}`);
  }

  async execute(
    requestContext: RequestContext,
    eventBus: IExecutionEventBus
  ): Promise<void> {
    const userMessage = requestContext.userMessage;
    const existingTask = requestContext.task;
    
    const taskId = existingTask?.id || uuidv4();
    const contextId = userMessage.contextId || existingTask?.contextId || uuidv4();

    console.log(`A2A JS Agent verarbeitet Nachricht: ${userMessage.parts[0]?.text}`);

    // Neue Aufgabe erstellen
    if (!existingTask) {
      const initialTask: Task = {
        kind: 'task',
        id: taskId,
        contextId: contextId,
        status: {
          state: TaskState.Submitted,
          timestamp: new Date().toISOString(),
        },
        history: [userMessage],
        metadata: userMessage.metadata,
        artifacts: [],
      };
      eventBus.publish(initialTask);
    }

    // Statusaktualisierung veröffentlichen
    const workingUpdate: TaskStatusUpdateEvent = {
      kind: 'status-update',
      taskId: taskId,
      contextId: contextId,
      status: {
        state: TaskState.Working,
        message: {
          kind: 'message',
          role: 'agent',
          messageId: uuidv4(),
          parts: [{ kind: 'text', text: 'A2A JS Agent denkt nach...' }],
          taskId: taskId,
          contextId: contextId,
        },
        timestamp: new Date().toISOString(),
      },
      final: false,
    };
    eventBus.publish(workingUpdate);

    // Verarbeitungszeit simulieren
    await new Promise(resolve => setTimeout(resolve, 1000));

    // Abbruchstatus prüfen
    if (this.cancelledTasks.has(taskId)) {
      const cancelledUpdate: TaskStatusUpdateEvent = {
        kind: 'status-update',
        taskId: taskId,
        contextId: contextId,
        status: {
          state: TaskState.Canceled,
          timestamp: new Date().toISOString(),
        },
        final: true,
      };
      eventBus.publish(cancelledUpdate);
      return;
    }

    // Antwort generieren
    const userText = userMessage.parts[0]?.text || '';
    let responseText = '';
    
    if (userText.toLowerCase().includes('hello') || userText.toLowerCase().includes('hi')) {
      responseText = `Hallo! Willkommen im A2A JS SDK! Ich bin ein intelligenter Agent, erstellt mit A2A JS.`;
    } else if (userText.toLowerCase().includes('a2a js')) {
      responseText = `Das A2A JS SDK ist eine leistungsstarke JavaScript-Bibliothek zum Erstellen intelligenter Agentenanwendungen!`;
    } else {
      responseText = `Ich bin ein A2A JS Agent und habe Ihre Nachricht erhalten: "${userText}". Danke für die Verwendung des A2A JS SDKs!`;
    }

    // Endergebnis veröffentlichen
    const finalUpdate: TaskStatusUpdateEvent = {
      kind: 'status-update',
      taskId: taskId,
      contextId: contextId,
      status: {
        state: TaskState.Completed,
        message: {
          kind: 'message',
          role: 'agent',
          messageId: uuidv4(),
          parts: [{ kind: 'text', text: responseText }],
          taskId: taskId,
          contextId: contextId,
        },
        timestamp: new Date().toISOString(),
      },
      final: true,
    };
    eventBus.publish(finalUpdate);
  }
}

Schritt 3: A2A JS Server starten

import express from 'express';
import {
  A2AExpressApp,
  DefaultRequestHandler,
  InMemoryTaskStore
} from "@a2a-js/sdk";

const taskStore = new InMemoryTaskStore();
const agentExecutor = new HelloWorldA2AJSExecutor();

const requestHandler = new DefaultRequestHandler(
  myAgentCard,
  taskStore,
  agentExecutor
);

const appBuilder = new A2AExpressApp(requestHandler);
const expressApp = appBuilder.setupRoutes(express(), '');

const PORT = process.env.PORT || 3000;
expressApp.listen(PORT, () => {
  console.log(`A2A JS Agent-Server gestartet auf http://localhost:${PORT}`);
  console.log(`A2A JS Agent-Karte: http://localhost:${PORT}/.well-known/agent.json`);
  console.log('Drücken Sie Ctrl+C, um den A2A JS Server zu beenden');
});

A2A JS Server-Entwicklung

Aufgaben-Speicher

A2A JS bietet einen In-Memory-Aufgaben-Speicher und ermöglicht auch die Implementierung benutzerdefinierter Speicher:

import { TaskStore, Task } from "@a2a-js/sdk";

class CustomA2AJSTaskStore implements TaskStore {
  private tasks = new Map<string, Task>();

  async getTask(taskId: string): Promise<Task | undefined> {
    console.log(`A2A JS Aufgabe wird abgerufen: ${taskId}`);
    return this.tasks.get(taskId);
  }

  async setTask(task: Task): Promise<void> {
    console.log(`A2A JS Aufgabe wird gespeichert: ${task.id}`);
    this.tasks.set(task.id, task);
  }

  async deleteTask(taskId: string): Promise<void> {
    console.log(`A2A JS Aufgabe wird gelöscht: ${taskId}`);
    this.tasks.delete(taskId);
  }
}

Middleware-Unterstützung

A2A JS basiert auf Express.js und unterstützt alle Standard-Middleware:

import cors from 'cors';
import express from 'express';

const app = express();

// A2A JS Server-Middleware-Konfiguration
app.use(cors());
app.use(express.json());

// Benutzerdefinierte A2A JS Logging-Middleware
app.use((req, res, next) => {
  console.log(`A2A JS Anfrage: ${req.method} ${req.path}`);
  next();
});

A2A JS Client-Verwendung

Grundlegende Client-Operationen

import { A2AClient, MessageSendParams } from "@a2a-js/sdk";
import { v4 as uuidv4 } from "uuid";

const client = new A2AClient("http://localhost:3000");

async function testA2AJSClient() {
  console.log("Teste A2A JS Client...");
  
  const messageParams: MessageSendParams = {
    message: {
      messageId: uuidv4(),
      role: "user",
      parts: [{ kind: "text", text: "Hallo, A2A JS!" }],
      kind: "message"
    },
    configuration: {
      blocking: true,
      acceptedOutputModes: ['text/plain']
    }
  };

  try {
    const response = await client.sendMessage(messageParams);
    
    if (response.error) {
      console.error("A2A JS Client-Fehler:", response.error);
      return;
    }

    console.log("A2A JS Antwort:", response.result);
  } catch (error) {
    console.error("A2A JS Kommunikationsfehler:", error);
  }
}

testA2AJSClient();

A2A JS Streaming

A2A JS unterstützt Echtzeit-Streaming-Kommunikation:

import { A2AClient, TaskStatusUpdateEvent } from "@a2a-js/sdk";

async function streamA2AJSResponse() {
  const client = new A2AClient("http://localhost:3000");
  
  console.log("Starte A2A JS Streaming...");
  
  const streamParams = {
    message: {
      messageId: uuidv4(),
      role: "user",
      parts: [{ kind: "text", text: "Streaming-Konversation mit A2A JS" }],
      kind: "message"
    }
  };

  try {
    const stream = client.sendMessageStream(streamParams);
    
    for await (const event of stream) {
      if (event.kind === 'task') {
        console.log(`A2A JS Aufgabe erstellt: ${event.id}`);
      } else if (event.kind === 'status-update') {
        const statusEvent = event as TaskStatusUpdateEvent;
        console.log(`A2A JS Statusaktualisierung: ${statusEvent.status.state}`);
        
        if (statusEvent.status.message?.parts[0]?.text) {
          console.log(`A2A JS Nachricht: ${statusEvent.status.message.parts[0].text}`);
        }
        
        if (statusEvent.final) {
          console.log("A2A JS Streaming abgeschlossen");
          break;
        }
      }
    }
  } catch (error) {
    console.error("A2A JS Streaming-Fehler:", error);
  }
}

A2A JS Erweiterte Funktionen

Artefakt-Verarbeitung

A2A JS unterstützt die Generierung und Verwaltung von Artefakten:

import { TaskArtifactUpdateEvent } from "@a2a-js/sdk";

// Artefakt vom AgentExecutor veröffentlichen
const artifactUpdate: TaskArtifactUpdateEvent = {
  kind: 'artifact-update',
  taskId: taskId,
  contextId: contextId,
  artifact: {
    artifactId: "a2a-js-example",
    name: "A2A JS Beispiel-Datei",
    parts: [{ 
      text: `# Von A2A JS generierter Inhalt\n\nDies ist eine Beispiel-Datei, die mit dem A2A JS SDK generiert wurde.`
    }],
  },
  append: false,
  lastChunk: true,
};
eventBus.publish(artifactUpdate);

Sicherheitskonfiguration

Konfiguration der Sicherheitsoptionen für den A2A JS Agenten:

const secureAgentCard: AgentCard = {
  name: 'Sicherer A2A JS Agent',
  description: 'A2A JS Agent mit Sicherheit',
  // ... weitere Konfigurationen
  securitySchemes: {
    apiKey: {
      type: 'apiKey',
      name: 'X-API-Key',
      in: 'header'
    }
  },
  security: [{
    apiKey: []
  }]
};

A2A JS Best Practices

1. Fehlerbehandlung

Implementierung einer umfassenden Fehlerbehandlung in A2A JS Anwendungen:

class RobustA2AJSExecutor implements AgentExecutor {
  async execute(requestContext: RequestContext, eventBus: IExecutionEventBus) {
    try {
      // A2A JS Ausführungslogik
      await this.processRequest(requestContext, eventBus);
    } catch (error) {
      console.error("A2A JS Ausführungsfehler:", error);
      
      // Fehlerstatus veröffentlichen
      const errorUpdate: TaskStatusUpdateEvent = {
        kind: 'status-update',
        taskId: requestContext.task?.id || uuidv4(),
        contextId: requestContext.userMessage.contextId || uuidv4(),
        status: {
          state: TaskState.Failed,
          message: {
            kind: 'message',
            role: 'agent',
            messageId: uuidv4(),
            parts: [{ kind: 'text', text: 'Bei der A2A JS Verarbeitung ist ein Fehler aufgetreten. Bitte versuchen Sie es später erneut.' }],
          },
          timestamp: new Date().toISOString(),
        },
        final: true,
      };
      eventBus.publish(errorUpdate);
    }
  }
}

2. Leistungsoptimierung

Optimierung der Leistung von A2A JS Anwendungen:

// A2A JS Client-Optimierung mit Verbindungspooling
const client = new A2AClient("http://localhost:3000", {
  keepAlive: true,
  timeout: 30000
});

// Caching von A2A JS Agent-Antworten
class CachedA2AJSExecutor implements AgentExecutor {
  private cache = new Map<string, string>();
  
  async execute(requestContext: RequestContext, eventBus: IExecutionEventBus) {
    const userText = requestContext.userMessage.parts[0]?.text || '';
    const cacheKey = `a2a-js-${userText}`;
    
    // A2A JS Cache prüfen
    if (this.cache.has(cacheKey)) {
      console.log("Verwende gecachte A2A JS Antwort");
      // Gecachte Antwort zurückgeben
    }
    
    // Neue Anfrage verarbeiten und Ergebnis cachen
  }
}

3. Protokollierung

Hinzufügen einer detaillierten Protokollierung in A2A JS Anwendungen:

import { createLogger, format, transports } from 'winston';

const a2aJSLogger = createLogger({
  level: 'info',
  format: format.combine(
    format.timestamp(),
    format.printf(({ timestamp, level, message }) => {
      return `[A2A JS] ${timestamp} ${level}: ${message}`;
    })
  ),
  transports: [
    new transports.Console(),
    new transports.File({ filename: 'a2a-js.log' })
  ]
});

// Verwendung im A2A JS Code
a2aJSLogger.info('A2A JS Agent erfolgreich gestartet');
a2aJSLogger.error('A2A JS Verarbeitungsfehler', { error: errorDetails });

A2A JS Fehlerbehebung

Behebung häufiger Probleme

1. A2A JS Verbindungsprobleme

// A2A JS Server-Verbindung prüfen
async function checkA2AJSConnection() {
  try {
    const client = new A2AClient("http://localhost:3000");
    const response = await fetch("http://localhost:3000/.well-known/agent.json");
    
    if (response.ok) {
      console.log("A2A JS Server-Verbindung normal");
    } else {
      console.error("Anormale A2A JS Server-Antwort:", response.status);
    }
  } catch (error) {
    console.error("A2A JS Verbindungsfehler:", error);
  }
}

Versuchen Sie auch diese Methoden:

A2A Protokoll-Validator
Anleitung: Wie man die Agent-Karte validiert

2. A2A JS Typfehler

Stellen Sie sicher, dass Sie die A2A JS Typen korrekt importieren:

// A2A JS Typen korrekt importieren
import {
  AgentCard,
  AgentExecutor,
  A2AClient,
  Task,
  TaskState,
  Message,
  MessageSendParams
} from "@a2a-js/sdk";

3. A2A JS Leistungs-Debugging

// A2A JS Leistungsüberwachung
class PerformanceA2AJSExecutor implements AgentExecutor {
  async execute(requestContext: RequestContext, eventBus: IExecutionEventBus) {
    const startTime = Date.now();
    console.log(`A2A JS Verarbeitung gestartet: ${startTime}`);
    
    try {
      // A2A JS Logik
      await this.processRequest(requestContext, eventBus);
    } finally {
      const endTime = Date.now();
      console.log(`A2A JS Verarbeitung abgeschlossen, verstrichene Zeit: ${endTime - startTime}ms`);
    }
  }
}

Zusammenfassung

Das A2A JS SDK ist ein leistungsstarkes Werkzeug zum Erstellen intelligenter Agentenanwendungen. In diesem Tutorial haben wir gelernt:

Die Grundkonzepte und Architektur von A2A JS
Wie man A2A JS Agenten erstellt und konfiguriert
A2A JS Server- und Client-Entwicklung
Erweiterte Funktionen und Best Practices von A2A JS
Wie man häufige Probleme in A2A JS Anwendungen löst

Sie können jetzt Ihre eigene A2A JS Anwendung erstellen! Das A2A JS SDK bietet umfangreiche Funktionen, um Ihnen beim Erstellen leistungsstarker und erweiterbarer intelligenter Agentensysteme zu helfen.

Für weitere A2A JS Ressourcen und Beispiele besuchen Sie:

Starten Sie Ihre A2A JS Entwicklungsreise! 🚀