Content Planner Agent basierend auf A2A und ADK

Projektübersicht

Der Content Planner Agent ist ein intelligenter Content-Planungsagent, der auf Google Agent Development Kit (ADK) und Python A2A SDK aufbaut. Dieser Agent kann detaillierte Content-Outlines basierend auf hochrangigen Content-Beschreibungen erstellen.

Was ist das A2A-Protokoll

Das A2A-Protokoll (Agent2Agent Protocol) ist ein offenes Standardprotokoll, das speziell für KI-Agenten entwickelt wurde. Sein Kernziel ist es, Interoperabilität zwischen Agenten verschiedener Plattformen und Technologie-Stacks zu erreichen, sodass sie wie "Kollegen" zusammenarbeiten können, um Aufgaben zu erledigen, unabhängig von der zugrunde liegenden Technologie.

Tech Stack

Python: 3.10+
UV: Python-Paketmanager
Google ADK: Google Agent Development Kit
A2A SDK: Agent-to-Agent-Kommunikationsprotokoll
Gemini 2.5 Flash: Großes Sprachmodell
Google Search: Suchwerkzeug
Uvicorn: ASGI-Server

Voraussetzungen

1. Umgebungseinrichtung

Stellen Sie sicher, dass Ihr System die folgende Software installiert hat:

# Python-Version prüfen (3.10+ erforderlich)
python --version

# UV-Paketmanager installieren (falls noch nicht installiert)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Oder pip verwenden
pip install uv

2. API-Schlüssel

Sie müssen Google API-Schlüssel erhalten, um Gemini-Modelle und Google Search-Funktionalität zu verwenden:

Besuchen Sie Google AI Studio
Erstellen Sie einen neuen API-Schlüssel
Speichern Sie den Schlüssel für spätere Verwendung

Projektstruktur

samples/python/agents/content_planner/
├── __init__.py                 # Paket-Initialisierungsdatei
├── __main__.py                # Haupt-Eingangsdatei
├── agent_executor.py          # Agent-Executor
├── content_planner_agent.py   # Content Planner Agent-Definition
├── pyproject.toml            # Projekt-Konfigurationsdatei
├── requirements.txt          # Abhängigkeitsliste
├── .env.example             # Umgebungsvariablen-Beispiel
└── README.md               # Projektdokumentation

Schnellstart

Schritt 1: Projekt klonen und zum Verzeichnis navigieren

# Angenommen, Sie haben bereits das a2a-samples-Projekt
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/content_planner

Schritt 2: Umgebungsvariablen konfigurieren

# Umgebungsvariablen-Beispieldatei kopieren
cp .env.example .env

# .env-Datei bearbeiten und Ihren Google API-Schlüssel hinzufügen
echo "GOOGLE_API_KEY=your_actual_api_key_here" > .env

Schritt 3: Abhängigkeiten installieren und Agent ausführen

# UV verwenden, um Abhängigkeiten zu installieren und das Projekt auszuführen
uv run .

# Hinweis:
"gradio>=5.30.0" wird im aktuellen Agent nicht benötigt.

Standardmäßig startet der Agent auf http://localhost:10001.

Schritt 4: Agent testen (neues Terminalfenster)

# Zum CLI-Client-Verzeichnis navigieren
cd samples/python/hosts/cli

# Mit dem Agent verbinden und eine Nachricht senden
uv run . --agent http://localhost:10001

Schritt 5: Mit dem Agent interagieren

Im CLI-Client können Sie Nachrichten wie diese senden:

Create an outline for a short, upbeat, and encouraging X post about learning Java

Code-Erklärung

1. Haupt-Eingangsdatei (`main.py`)

@click.command()
@click.option("--host", default="localhost")
@click.option("--port", default=10001)
def main(host, port):
    # Agent-Karte (Metadaten)
    agent_card = AgentCard(
        name='Content Planner Agent',
        description=content_planner_agent.description,
        url=f'http://{host}:{port}',
        version="1.0.0",
        defaultInputModes=["text", "text/plain"],
        defaultOutputModes=["text", "text/plain"],
        capabilities=AgentCapabilities(streaming=True),
        skills=[
            AgentSkill(
                id="content_planner",
                name="Creates outlines for content",
                description="Creates outlines for content given a high-level description of the content",
                tags=["plan", "outline"],
                examples=[
                    "Create an outline for a short, upbeat, and encouraging X post about learning Java",
                ],
            )
        ],
    )

Erklärung der Hauptkomponenten:

AgentCard: Agent-Metadatenkarte mit Name, Beschreibung, URL, Version usw.
AgentSkill: Agent-Skill-Definition mit ID, Name, Beschreibung, Tags und Beispielen
AgentCapabilities: Agent-Fähigkeitskonfiguration wie Streaming-Unterstützung

2. Agent-Definition (`content_planner_agent.py`)

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="content_planner_agent",
    model="gemini-2.5-flash",
    description=("Planning agent that creates a detailed and logical outline for a piece of content,"
                 "given a high-level description."),
    instruction=("You are an expert content planner. Your task is to create a detailed and logical outline for a piece"
                 "of content, given a high-level description."),
    tools=[google_search],
)

Hauptfunktionen:

Model: Verwendet Gemini 2.5 Flash als Basis-LLM
Tools: Integriert Google Search-Tool für relevante Informationsbeschaffung
Instructions: Definiert klar die Rolle und Aufgaben des Agents

3. Agent-Executor (`agent_executor.py`)

class ADKAgentExecutor(AgentExecutor):
    def __init__(self, agent, status_message="Processing request...", artifact_name="response"):
        self.agent = agent
        self.status_message = status_message
        self.artifact_name = artifact_name
        self.runner = Runner(
            app_name=agent.name,
            agent=agent,
            artifact_service=InMemoryArtifactService(),
            session_service=InMemorySessionService(),
            memory_service=InMemoryMemoryService(),
        )

Kernfunktionalität:

Runner: ADK-Runner, der die Agent-Ausführung verwaltet
Service-Komponenten:
- ArtifactService: Verwaltet generierte Artefakte
- SessionService: Verwaltet Sitzungszustand
- MemoryService: Verwaltet Gesprächsspeicher

System-Architektur-Flussdiagramm

graph TB
    A[Benutzeranfrage] --> B[A2A CLI-Client]
    B --> C[HTTP-Anfrage]
    C --> D[A2A Starlette-Anwendung]
    D --> E[DefaultRequestHandler]
    E --> F[ADKAgentExecutor]
    F --> G[ADK Runner]
    G --> H[Content Planner Agent]
    H --> I[Gemini 2.5 Flash-Modell]
    H --> J[Google Search-Tool]
    I --> K[Content-Outline-Generierung]
    J --> K
    K --> L[Antwort-Artefakt]
    L --> M[Aufgabenabschluss]
    M --> N[Ergebnis an Benutzer zurückgeben]
    
    subgraph "ADK-Komponenten"
        O[InMemoryArtifactService]
        P[InMemorySessionService]
        Q[InMemoryMemoryService]
    end
    
    G --> O
    G --> P
    G --> Q

Detaillierter Ausführungsfluss

1. Initialisierungsphase

sequenceDiagram
    participant Main as __main__.py
    participant Agent as content_planner_agent
    participant Executor as ADKAgentExecutor
    participant Server as A2AStarletteApplication
    
    Main->>Agent: Agent-Konfiguration laden
    Main->>Executor: Executor-Instanz erstellen
    Main->>Server: A2A-Server erstellen
    Server->>Server: Uvicorn-Server starten

2. Anfrageverarbeitungsphase

sequenceDiagram
    participant Client as CLI-Client
    participant Server as A2A-Server
    participant Handler as DefaultRequestHandler
    participant Executor as ADKAgentExecutor
    participant Runner as ADK Runner
    participant Model as Gemini 2.5 Flash
    participant Search as Google Search
    
    Client->>Server: Content-Planungsanfrage senden
    Server->>Handler: Anfrage weiterleiten
    Handler->>Executor: Agent-Aufgabe ausführen
    Executor->>Runner: ADK-Runner starten
    Runner->>Model: Gemini-Modell aufrufen
    Runner->>Search: Google-Suche ausführen
    Model->>Runner: Generierten Content zurückgeben
    Search->>Runner: Suchergebnisse zurückgeben
    Runner->>Executor: Ergebnisse zusammenführen
    Executor->>Handler: Artefakt zurückgeben
    Handler->>Server: Aufgabe abschließen
    Server->>Client: Content-Outline zurückgeben

Erweiterte Konfiguration

Benutzerdefinierter Port

# Agent auf angegebenem Port starten
uv run . --port=8080

Benutzerdefinierter Host

# Auf angegebenem Host und Port starten
uv run . --host=0.0.0.0 --port=8080

Umgebungsvariablen-Konfiguration

Sie können weitere Optionen in der .env-Datei konfigurieren:

GOOGLE_API_KEY=your_api_key_here
# Sie können weitere Konfigurationselemente hinzufügen
LOG_LEVEL=INFO

Fehlerbehebung

Häufige Probleme

API-Schlüssel-Fehler

Fehler: Invalid API key
Lösung: Überprüfen Sie, ob GOOGLE_API_KEY in der .env-Datei korrekt ist

Port bereits in Verwendung

Fehler: Port 10001 is already in use
Lösung: Verwenden Sie den --port-Parameter, um einen anderen Port anzugeben

Abhängigkeitsinstallation fehlgeschlagen

Fehler: Failed to install dependencies
Lösung: Stellen Sie sicher, dass UV ordnungsgemäß installiert ist, versuchen Sie uv sync

Erweiterung und Anpassung

Neue Tools hinzufügen

Fügen Sie neue Tools in content_planner_agent.py hinzu:

from google.adk.tools import google_search, web_search

root_agent = Agent(
    # ... andere Konfigurationen
    tools=[google_search, web_search],  # Weitere Tools hinzufügen
)

Modell ändern

root_agent = Agent(
    name="content_planner_agent",
    model="gemini-1.5-pro",  # Anderes Modell verwenden
    # ... andere Konfigurationen
)

Benutzerdefinierte Anweisungen

root_agent = Agent(
    # ... andere Konfigurationen
    instruction=(
        "Sie sind ein spezialisierter Content-Planer für technische Dokumentation. "
        "Erstellen Sie detaillierte Outlines, die Code-Beispiele und Best Practices enthalten."
    ),
)

Best Practices

Sicherheit:
- API-Schlüssel immer in Umgebungsvariablen speichern
- .env-Dateien nicht in die Versionskontrolle committen
Leistungsoptimierung:
- Angemessene Modellgrößen verwenden
- Speicher- und Sitzungsdienste ordnungsgemäß konfigurieren
Fehlerbehandlung:
- Ordnungsgemäße Fehlerbehandlung und Protokollierung implementieren
- Aussagekräftige Fehlermeldungen bereitstellen
Testen:
- Unit-Tests und Integrationstests schreiben
- Agent-Antworten mit verschiedenen Eingaben testen

Zusammenfassung

Der Content Planner Agent zeigt, wie man intelligente Agenten mit Google ADK und dem A2A-Protokoll erstellt. Durch diesen Leitfaden sollten Sie in der Lage sein:

Die gesamte Projektarchitektur zu verstehen
Den Agent erfolgreich auszuführen und zu testen
Nach Bedarf anzupassen und zu erweitern
Häufige Probleme zu lösen

Dieser Agent kann als Grundlage für den Aufbau komplexerer Multi-Agent-Systeme dienen, wie z.B. vollständige Content-Erstellungsworkflows.