Design wechseln

KI-Agent-Entwicklung in der Praxis: Architekturdesign und Implementierungsleitfaden

Ein ReAct-Agent hing nach zwanzig Minuten in einer Endlosschleife fest und rief immer wieder dasselbe Tool auf. Ursache: kein maxIterations – danach erzwungen stoppen, um Deadlocks zu vermeiden. Das ist eine der häufigsten Fallen in der Agent-Entwicklung: ReAct-Agents in Endlosschleifen, Multi-Agent-Systeme ohne Konvergenz, Plan-and-Execute unflexibel bei dynamischen Aufgaben.

Die Agent-Architektur hat drei Ebenen: Direkter Modellaufruf für Einzelschritte, Single Agent + Tools als Standard für die meisten Szenarien, Multi-Agent-Orchestrierung nur mit Bedacht einführen. Drei Kernmuster mit jeweils passenden Einsatzfeldern: ReAct für dynamische Entscheidungen, Plan-and-Execute für stabile Abläufe, Multi-Agent für fachliche Spezialisierung. Azure empfiehlt, Group-Chat-Agents auf maximal drei zu begrenzen – mehr erschwert die Konvergenz.

Dieser Artikel ordnet zwei Jahre Praxiserfahrung: drei Architekturmuster mit Prinzip und Code, fünf Multi-Agent-Orchestrierungsmuster, Framework-Auswahl zwischen LangChain, AutoGen, CrewAI und Claude Agent SDK – und wie Sie mit dem Claude Agent SDK einen lauffähigen Agent bauen.

1. Drei Ebenen der Agent-Architektur

Zuerst ein Prinzip, das viele Einsteiger übersehen: Wenn eine einfache Lösung reicht, nicht unnötig komplex bauen.

Azure unterteilt Agent-Architekturen in drei Ebenen – eine besonders praktische Einteilung:

1.1 Direkter Modellaufruf (Direct Model Call)

Die einfachste Ebene. Sie geben eine Aufgabe an das Modell, es liefert direkt eine Antwort.

// Grundlegender Aufruf
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Fasse diesen Text zusammen...' }]
});

Geeignet für: Einzelschritte, hohe Deterministik, keine externen Tools. Beispiele: Textzusammenfassung, Übersetzung, Code-Vervollständigung.

Vorteile: einfach, günstig, kontrollierbar. Nachteile: keine mehrstufige Reasoning-Kette, keine Tool-Aufrufe.

1.2 Single Agent + Tools

Das ist die Standardwahl in den meisten Unternehmensszenarien. Der Agent kann Tools aufrufen und mehrstufige Aufgaben bearbeiten.

// LangChain Single-Agent-Beispiel
import { ChatAnthropic } from '@langchain/anthropic';
import { AgentExecutor, createToolCallingAgent } from 'langchain/agents';
import { tool } from '@langchain/core/tools';
import { z } from 'zod';

// Tool zur Wetterabfrage
const weatherTool = tool(
  async ({ city }) => {
    // Simulierter Wetter-API-Aufruf
    return `${city}: heute sonnig, 22°C`;
  },
  {
    name: 'get_weather',
    description: 'Wetterinformationen für eine Stadt abrufen',
    schema: z.object({
      city: z.string().describe('Stadtname'),
    }),
  }
);

const model = new ChatAnthropic({
  model: 'claude-sonnet-4-20250514',
  temperature: 0,
});

const agent = await createToolCallingAgent({
  llm: model,
  tools: [weatherTool],
  prompt: 'Du bist ein hilfreicher Assistent.',
});

const executor = AgentExecutor.fromAgentAndTools({
  agent,
  tools: [weatherTool],
});

// Ausführen
const result = await executor.invoke({
  input: 'Wie ist das Wetter heute in Peking?',
});

Geeignet für: Tool-Aufrufe, zerlegbare Aufgaben, relativ feste Schrittfolgen. Beispiele: Datenanalyse, Code-Ausführung, API-Orchestrierung.

1.3 Multi-Agent-Orchestrierung

Die komplexeste Ebene. Mehrere spezialisierte Agents arbeiten zusammen.

Ehrlich gesagt: Weniger Szenarien brauchen diese Ebene, als man denkt. Multi-Agent bedeutet Koordinationsaufwand, komplexeres State-Management und exponentiell schwierigeres Debugging.

Geeignet für: domänenübergreifende komplexe Aufgaben, fachliche Spezialisierung, wenn ein einzelner Agent nicht reicht. Beispiele: Software-Pipeline (Anforderungen → Design → Code → Tests), komplexe Entscheidungssysteme.

1.4 Wie wählen? Eine Entscheidungstabelle

Ihr SzenarioEmpfohlene EbeneBegründung
Einfache Q&A, TextverarbeitungDirekter ModellaufrufReicht aus – kein Over-Engineering
Datenbank, API-Aufrufe nötigSingle Agent + ToolsKlassische Lösung, stabil
Aufgabe zerlegbar, Schritte unsicherSingle Agent + Tools (ReAct)Agent plant Schritte selbst
Mehrere Fachrollen nötigMulti-Agent-OrchestrierungVorsichtig – wirklich nötig?

Kurz gesagt: Einfach anfangen, bei Bedarf erweitern.

2. Drei zentrale Architekturmuster im Detail

Nach der Ebenenwahl folgt die Musterwahl. Die drei Muster schließen sich nicht aus – oft kombiniert man sie.

2.1 ReAct (Reasoning + Acting)

ReAct steht für Reasoning + Acting. Kernidee: Das Modell denkt und handelt gleichzeitig.

Funktionsweise:

Benutzereingabe → Thought (Denken) → Action (Handeln) → Observation (Beobachten) → Schleife oder Ende

Beispiel: „Ist das Wetter morgen in Peking für Outdoor-Sport geeignet?“

  1. Thought: Ich muss zuerst das Wetter für morgen in Peking abfragen
  2. Action: Tool get_weather aufrufen, Parameter city: "Peking"
  3. Observation: Morgen bewölkt, 18–25°C, 10 % Niederschlagswahrscheinlichkeit
  4. Thought: Temperatur angenehm, wenig Regen – geeignet für Outdoor-Sport
  5. Final Answer: Morgen in Peking geeignet; leichte Jacke empfohlen

Code-Implementierung (LangChain):

import { ChatAnthropic } from '@langchain/anthropic';
import { AgentExecutor, createReactAgent } from 'langchain/agents';
import { pull } from 'langchain/hub';

// ReAct-Prompt-Vorlage
const prompt = await pull('hwchase17/react');

const agent = await createReactAgent({
  llm: model,
  tools: [weatherTool, searchTool], // Ihre Tool-Liste
  prompt,
});

// Maximale Iterationen setzen – Endlosschleifen vermeiden!
const executor = AgentExecutor.fromAgentAndTools({
  agent,
  tools: [weatherTool, searchTool],
  maxIterations: 10, // Wichtig: Deadlock-Schutz
  verbose: true, // Reasoning ausgeben – unverzichtbar beim Debuggen
});

Vor- und Nachteile:

VorteileNachteile
Hohe Flexibilität bei dynamischen AufgabenKann in Endlosschleifen geraten
Transparenter Reasoning-Prozess, gut debuggbarHöhere Kosten pro Aufruf
Keine vordefinierten Schritte nötigBegrenzte Planungsfähigkeit bei komplexen Mehrschritt-Aufgaben

Praxis-Tipp: Setzen Sie unbedingt maxIterations – sonst läuft der Agent bei unlösbaren Aufgaben endlos weiter. Mein erster ReAct-Agent lief deshalb eine ganze Nacht.

2.2 Plan-and-Execute

ReAct geht Schritt für Schritt vor und verliert bei komplexen Aufgaben leicht den Fokus. Plan-and-Execute dreht das um: Zuerst Plan, dann schrittweise Ausführung.

Funktionsweise:

Benutzereingabe → Planner erzeugt Plan → Executor führt Schritte aus → Ergebnis

Code-Implementierung (LangGraph):

import { ChatAnthropic } from '@langchain/anthropic';
import { StateGraph, END } from '@langchain/langgraph';

// Zustandsstruktur
interface AgentState {
  input: string;
  plan: string[];
  pastSteps: string[];
  response: string;
}

// Planungsknoten: Ausführungsplan erzeugen
async function planNode(state: AgentState): Promise<AgentState> {
  const plannerPrompt = `Gegebenes Nutzerziel: ${state.input}
Erstelle einen detaillierten Ausführungsplan, ein String pro Schritt, als JSON-Array zurückgeben.`;

  const response = await model.invoke(plannerPrompt);
  const plan = JSON.parse(response.content as string);
  return { ...state, plan };
}

// Ausführungsknoten: einen Planschritt ausführen
async function executeNode(state: AgentState): Promise<AgentState> {
  const currentStep = state.plan[0];
  const result = await executor.invoke({ input: currentStep });

  return {
    ...state,
    plan: state.plan.slice(1), // Erledigten Schritt entfernen
    pastSteps: [...state.pastSteps, `${currentStep}: ${result.output}`],
  };
}

// Graph aufbauen
const workflow = new StateGraph<AgentState>({
  channels: {
    input: { value: null },
    plan: { value: null },
    pastSteps: { value: null, default: () => [] },
    response: { value: null },
  },
});

workflow.addNode('planner', planNode);
workflow.addNode('executor', executeNode);

// Kanten: nach Planung ausführen
workflow.addEdge('planner', 'executor');

// Bedingte Kante: prüfen, ob noch Schritte offen sind
workflow.addConditionalEdges('executor', (state) => {
  return state.plan.length > 0 ? 'executor' : END;
});

Vor- und Nachteile:

VorteileNachteile
Stabile Ausführung, kontrollierbare SchrittePlan nach Erstellung unflexibel
Gut für deterministische AufgabenSchwach bei stark dynamischer Umgebung
Einfaches Monitoring und AbbrechenPlanqualität hängt vom Planner ab

Aus der Praxis: Plan-and-Execute eignet sich besonders für „vorhersehbare Schritte“ – Batch-Datenverarbeitung, Berichtserstellung. Bei häufig wechselnder Strategie ist ReAct oft besser.

2.3 Multi-Agent (Multi-Agent-Kollaboration)

Wenn eine Aufgabe für einen einzelnen Agent zu groß wird, kommen mehrere Agents ins Spiel.

Kernidee: Jeder Agent fokussiert ein Fachgebiet – wie ein Team.

Code-Implementierung (Claude Agent SDK-Stil):

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

// Spezialisierte Agents anlegen
const researchAgent = new ClaudeAgent({
  name: 'researcher',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'Du bist Recherche-Experte und sammelst sowie strukturierst Informationen.',
  tools: ['WebSearch', 'WebFetch'],
});

const writerAgent = new ClaudeAgent({
  name: 'writer',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'Du bist Content-Experte und schreibst sowie überarbeitest Texte.',
  tools: ['Read', 'Write', 'Edit'],
});

const reviewerAgent = new ClaudeAgent({
  name: 'reviewer',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'Du bist Qualitätsprüfer und kontrollierst Genauigkeit und Lesbarkeit.',
  tools: ['Read'],
});

// Kollaborationsablauf
async function collaborativeWriting(topic: string) {
  // Schritt 1: Recherche
  const research = await researchAgent.run(`Recherchiere Thema: ${topic}`);

  // Schritt 2: Schreiben
  const draft = await writerAgent.run(
    `Schreibe einen Artikel basierend auf diesen Rechercheergebnissen:\n${research}`
  );

  // Schritt 3: Review
  const review = await reviewerAgent.run(
    `Prüfe folgenden Artikel und gib Verbesserungsvorschläge:\n${draft}`
  );

  // Schritt 4: Überarbeitung
  const final = await writerAgent.run(
    `Überarbeite den Artikel nach dem Review:\nEntwurf: ${draft}\nFeedback: ${review}`
  );

  return final;
}

Wann Multi-Agent sinnvoll ist:

  • Aufgabe braucht mehrere Fachkompetenzen (Programmierung + Design + Text)
  • Kontextfenster eines einzelnen Agents reicht nicht
  • Klare fachliche Rollen nötig

Warnung: Debugging-Kosten steigen exponentiell. Zustandssynchronisation, Nachrichten und Fehlerbehandlung zwischen Agents werden schnell komplex. Wenn Single Agent reicht – nicht künstlich Multi-Agent erzwingen.

3. Fünf Multi-Agent-Orchestrierungsmuster

Wenn Multi-Agent wirklich nötig ist, wählen Sie das Orchestrierungsmuster. Diese fünf Azure-Muster decken die meisten Fälle ab.

3.1 Sequential (sequenzielle Orchestrierung)

Das intuitivste Muster: Ausgabe von Agent A ist Eingabe von Agent B – wie eine Pipeline.

[Agent A] → [Agent B] → [Agent C] → Endergebnis

Einsatz: Dokument-Pipeline (Recherche → Entwurf → Lektorat → Veröffentlichung), Code-Generierungsabläufe.

Code-Beispiel:

// Sequenzielle Pipeline
async function sequentialPipeline(input: string) {
  const step1 = await researchAgent.run(input);
  const step2 = await writerAgent.run(step1.output);
  const step3 = await editorAgent.run(step2.output);
  return step3.output;
}

Hinweis: Ausgabeformat jedes Schritts vorab vereinbaren – sonst versteht der nachgelagerte Agent die Daten nicht.

3.2 Concurrent (parallele Orchestrierung)

Mehrere Agents bearbeiten dieselbe Eingabe parallel; Ergebnisse werden zusammengeführt.

           → [Agent A] →
[Eingabe]  → [Agent B] →  → [Aggregator] → Endergebnis
           → [Agent C] →

Einsatz: Multi-Perspektiven-Analyse, Aktienbewertung (Technik + Fundamental + News parallel), Code-Review (Security + Performance + Stil parallel).

Code-Beispiel:

// Parallele Analyse
async function concurrentAnalysis(code: string) {
  const [security, performance, style] = await Promise.all([
    securityAgent.run(`Security-Review:\n${code}`),
    performanceAgent.run(`Performance-Analyse:\n${code}`),
    styleAgent.run(`Code-Stil-Prüfung:\n${code}`),
  ]);

  // Ergebnisse zusammenführen
  return {
    security: security.output,
    performance: performance.output,
    style: style.output,
  };
}

Hinweis: Aggregationslogik planen – verschiedene Agents können widersprüchliche Empfehlungen liefern; Schiedsmechanismus nötig.

3.3 Group Chat (Gruppenchat-Orchestrierung)

Mehrere Agents diskutieren in einem „Chatraum“, bis Konsens oder Timeout.

[Agent A] ⇄ [Agent B] ⇄ [Agent C]
     ↑           ↓
   [Moderator/Koordinator]

Einsatz: Brainstorming, Qualitätsprüfung, Entscheidungen nach mehreren Runden.

Azure-Empfehlung: Group-Chat-Agents auf maximal drei begrenzen. Mehr wird schnell unproduktiv.

Code-Beispiel:

// Group-Chat (Pseudocode)
interface ChatMessage {
  sender: string;
  content: string;
}

async function groupChatDiscussion(
  topic: string,
  agents: ClaudeAgent[],
  maxRounds: number = 5
) {
  const history: ChatMessage[] = [];

  for (let round = 0; round < maxRounds; round++) {
    for (const agent of agents) {
      const response = await agent.run(
        `Diskussionsthema: ${topic}\nBisheriger Verlauf: ${JSON.stringify(history)}\nBitte Ihre Position.`
      );
      history.push({ sender: agent.name, content: response.output });

      // Konsens prüfen
      if (checkConsensus(history)) {
        return summarizeConsensus(history);
      }
    }
  }

  return 'Diskussion abgelaufen, kein Konsens';
}

Praxis-Tipp: Unbedingt maxRounds setzen – zwei starrköpfige Agents können endlos debattieren. Ein Moderator hilft, die Diskussion zu fokussieren.

3.4 Handoff (Übergabe-Orchestrierung)

Ein Agent beendet seinen Teil und übergibt an den nächsten.

[Agent A] erkennt Bedarf an B → Übergabe an [Agent B] → weiter bearbeiten

Einsatz: Support-Bot (Vertrieb → Technik → After-Sales), Fehlerbehebung (Diagnose → Reparatur → Verifikation).

Code-Beispiel:

// Handoff-Beispiel
const supportAgent = new ClaudeAgent({
  name: 'support',
  systemPrompt: `Du bist Support. Bei technischen Fragen antworte "HANDOFF:tech".
Bei After-Sales-Fragen antworte "HANDOFF:after_sales".`,
});

const techAgent = new ClaudeAgent({
  name: 'tech',
  systemPrompt: 'Du bist Technik-Support-Experte.',
});

async function handleWithHandoff(userInput: string) {
  let currentAgent = supportAgent;
  let response = await currentAgent.run(userInput);

  // Übergabesignal erkennen
  while (response.output.includes('HANDOFF:')) {
    const targetAgent = response.output.match(/HANDOFF:(\w+)/)?.[1];

    if (targetAgent === 'tech') currentAgent = techAgent;
    else if (targetAgent === 'after_sales') currentAgent = afterSalesAgent;

    response = await currentAgent.run(userInput);
  }

  return response.output;
}

Hinweis: Übergabelogik klar halten – Zyklen vermeiden (A an B, B zurück an A).

3.5 Magentic (magnetische Orchestrierung)

Das flexibelste Muster: Der Scheduler wählt dynamisch den passenden Agent.

[Aufgabenpool] → [Intelligenter Scheduler] → je nach Aufgabe [Agent A/B/C]

Einsatz: Systeme mit vielfältigen Aufgabentypen, dynamische Ressourcenzuweisung.

Implementierungsidee:

// Magentic-Scheduling
interface Task {
  type: string;
  priority: number;
  content: string;
}

async function magenticScheduling(task: Task) {
  // Passendsten Agent nach Aufgabentyp wählen
  const agentScores = await Promise.all(
    agents.map(async (agent) => {
      const score = await evaluateAgentFit(agent, task);
      return { agent, score };
    })
  );

  // Agent mit höchstem Score
  const bestAgent = agentScores.sort((a, b) => b.score - a.score)[0].agent;
  return bestAgent.run(task.content);
}

Hinweis: Passungsbewertung sauber designen – sonst wird Scheduling zur Zufallszuweisung.

3.6 Muster-Auswahl auf einen Blick

MusterEinsatzKomplexitätHauptrisiko
SequentialPipeline-AufgabenNiedrigBlockierung durch Schrittabhängigkeiten
ConcurrentParallele Multi-Perspektiven-AnalyseMittelKonflikte brauchen Schiedsmechanismus
Group ChatMehrstufige DiskussionsentscheidungenHochKeine Konvergenz, endlose Debatten
HandoffDynamische fachliche ÜbergabeMittelZyklen, Deadlock bei Übergabe
MagenticVielfältige AufgabentypenHochKomplexe Scheduling-Logik

4. Framework-Vergleich und Auswahl

Nach den Architekturmuster folgt die Framework-Frage – LangChain, AutoGen, CrewAI, Claude Agent SDK, alles mit eigenen Stärken.

Meine Einschätzung: Es gibt kein bestes Framework, nur das passende für Ihr Szenario.

4.1 Framework-Positionierung

FrameworkKernpositionStärkenEinsatz
LangChainAllgemeines Agent-FrameworkReiche Tool-Integration, ausgereiftes ReActSchnelle Prototypen, Produktion, viele Tool-Integrationen
AutoGenMulti-Agent-KollaborationDialogische Zusammenarbeit, Human-in-the-loopKomplexe Multi-Agent-Systeme, manuelle Eingriffe
CrewAIRollenspiel-KollaborationSchlanke API, intuitive KonzepteTeam-Simulation, klare Rollenverteilung
Claude Agent SDKClaude-nativCode-Verständnis, Dateioperationen, tiefe Claude-IntegrationClaude-Ökosystem, Code-Agents, Automatisierung

4.2 Framework-Details

LangChain: Etablierter Standard, reifes Ökosystem.

  • Vollständige TypeScript- und Python-Unterstützung
  • Viele eingebaute Tools und Integrationen
  • ReAct und Plan-and-Execute out of the box
  • Nachteil: API ändert sich häufig, Dokumentation hinkt manchmal hinterher

AutoGen: Von Microsoft, Favorit für Multi-Agent.

  • Kernkonzept: „Dialog“ – Agents kooperieren über Nachrichten
  • Human-in-the-loop unterstützt
  • Gut für mehrstufige Diskussionen und Entscheidungen
  • Nachteil: steile Lernkurve, Multi-Agent-Debugging mühsam

CrewAI: Neuer, Fokus auf Einfachheit.

  • Modellierung mit „Rolle“, „Aufgabe“, „Team“ – sehr intuitiv
  • Saubere API, schneller Einstieg
  • Gut für Multi-Agent-Prototypen
  • Nachteil: Ökosystem und Tool-Integration schwächer als LangChain

Claude Agent SDK: Offizielles Anthropic-Tool, 2026 neu.

  • Tiefe Integration mit Claude-Modellen
  • Eingebaute Datei-Lese-/Schreib-, Code-Edit- und Befehlsausführung
  • permissionMode für Berechtigungskontrolle
  • Wenn Claude Ihr Hauptmodell ist: erste Wahl

4.3 Auswahl-Leitfaden

Stellen Sie sich diese Fragen:

  1. Welches Modell ist Ihr Hauptmodell?

    • Claude → Claude Agent SDK bevorzugen
    • OpenAI → LangChain-Ökosystem reifer
    • Multi-Modell → LangChain oder AutoGen
  2. Wie komplex ist die Aufgabe?

    • Single Agent + Tools → LangChain reicht
    • Multi-Agent-Kollaboration → AutoGen oder CrewAI
    • Codebezogene Aufgaben → Claude Agent SDK
  3. Welcher Tech-Stack im Team?

    • Python-lastig → alle Frameworks unterstützt
    • TypeScript-lastig → LangChain und Claude Agent SDK stärker
  4. Brauchen Sie Human-in-the-loop?

    • Ja → AutoGen mit gutem Human-in-the-loop-Design
    • Nein → andere Frameworks ebenfalls möglich

4.4 Meine Empfehlung

Ehrlich: Für die meisten Szenariereicht LangChain. Tool-Integration und ReAct sind ausgereift, Community-Unterstützung stark.

Multi-Agent lohnt sich mit AutoGen, wenn die Aufgabe wirklich mehrere Fach-Agents braucht. Aber: Debugging-Kosten sind hoch – nicht aus „Technik-Enthusiasmus“ Multi-Agent erzwingen.

Als Claude-Power-User ist das Claude Agent SDK derzeit die beste Wahl – offiziell, beste Abstimmung mit Claude-Modellen.

5. Praxis – Agent mit dem Claude Agent SDK bauen

Genug Theorie – ein lauffähiger Code-Refactoring-Agent mit dem Claude Agent SDK.

5.1 Umgebung vorbereiten

# Abhängigkeiten installieren
npm install @anthropic-ai/claude-agent-sdk

# API Key setzen
export ANTHROPIC_API_KEY=your_api_key_here

5.2 Basis-Agent-Beispiel

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

// Code-Refactoring-Agent
const refactorAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit', 'Bash'],
  permissionMode: 'acceptEdits', // Bearbeitungen automatisch akzeptieren
  workingDirectory: './src', // Arbeitsverzeichnis
});

// Aufgabe ausführen
async function refactorCode(task: string) {
  const result = await refactorAgent.run(task);
  console.log('Refactoring-Ergebnis:', result);
  return result;
}

// Beispiel
refactorCode('auth.ts refaktorisieren: Callback-Stil zu async/await');

5.3 Wichtige Konfiguration

permissionMode (Berechtigungsmodus):

  • 'acceptEdits': Dateibearbeitungen automatisch akzeptieren
  • 'interactive': Jede Operation manuell bestätigen
  • 'planOnly': Nur Plan erzeugen, nicht ausführen

tools (verfügbare Tools):

  • Read: Datei lesen
  • Write: Neue Datei anlegen
  • Edit: Bestehende Datei bearbeiten
  • Bash: Shell-Befehle ausführen
  • Glob: Dateimuster-Matching
  • Grep: Inhaltsuche

5.4 Komplexeres Beispiel: Agent mit Constraints

const cautiousAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit', 'Bash'],
  permissionMode: 'interactive', // Vorsicht: manuelle Bestätigung
  maxIterations: 20, // Maximale Iterationen
  timeout: 300000, // 5 Minuten Timeout

  // System-Prompt: Verhaltensgrenzen
  systemPrompt: `Du bist Code-Refactoring-Experte.
Regeln:
1. Keine Testdateien löschen
2. package.json nicht ändern
3. Vor jeder Änderung Original sichern
4. Nach Änderung Tests ausführen und Funktion prüfen`,
});

async function safeRefactor(filePath: string) {
  try {
    const result = await cautiousAgent.run(
      `Refaktoriere ${filePath}, optimiere Struktur und Lesbarkeit.`
    );
    return result;
  } catch (error) {
    console.error('Refactoring fehlgeschlagen:', error);
    // Rollback-Logik...
  }
}

5.5 Best Practices

  1. Iterationen begrenzen: Endlosschleifen vermeiden
  2. Timeout setzen: Fallback für lange Läufe
  3. Berechtigungen staffeln: Sensibles mit interactive
  4. Backup: Wichtige Dateien vor Änderung sichern
  5. Tests: Nach Änderungen Tests ausführen

5.6 Debugging-Tipps

// Ausführliches Logging
const debugAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit'],
  verbose: true, // Detaillierten Ablauf ausgeben
});

// Events abonnieren
debugAgent.on('toolCall', (tool, args) => {
  console.log(`Tool-Aufruf: ${tool}, Parameter: ${JSON.stringify(args)}`);
});

debugAgent.on('thinking', (thought) => {
  console.log(`Agent denkt: ${thought}`);
});

Zum Abschluss

Die Kernidee bei der Agent-Architektur-Wahl ist einfach: Einfach anfangen, bei Bedarf erweitern.

Zuerst die Aufgabenkomplexität einschätzen:

  • Einzelschritt? Direkter Modellaufruf
  • Tools nötig? Single Agent + Tools
  • Wirklich mehrere Fachrollen? Dann Multi-Agent

Dann das Muster:

  • Dynamische Aufgabe? ReAct
  • Vorhersehbare Schritte? Plan-and-Execute
  • Fachliche Spezialisierung? Multi-Agent

Zuletzt das Framework:

  • Claude-Nutzer? Claude Agent SDK
  • Multi-Modell, viele Tools? LangChain
  • Multi-Agent-Kollaboration? AutoGen oder CrewAI

Am wichtigsten: Ausprobieren. Kleines Projekt, Agent zum Laufen bringen – ein paar Fallen später verstehen Sie es wirklich.

Fragen gerne in den Kommentaren – oder lesen Sie die beiden vorherigen Artikel „MCP Server Entwicklung Einstieg“ und „Agent Tool-Aufruf in der Praxis“. Die drei Artikel bauen aufeinander auf.

Einen Agent mit dem Claude Agent SDK aufbauen

Vom Setup bis zum ersten laufenden Agent – Schritt für Schritt

⏱️ Estimated time: 30 min

  1. 1

    Step 1: Abhängigkeiten installieren und Umgebung konfigurieren

    Führen Sie folgende Befehle aus:

    ```bash
    npm install @anthropic-ai/claude-agent-sdk
    export ANTHROPIC_API_KEY=your_api_key_here
    ```

    Hinweis: Den API Key erhalten Sie auf der Anthropic-Website. Speichern Sie ihn am besten in einer Umgebungsvariable.
  2. 2

    Step 2: Basis-Agent-Instanz anlegen

    Beim Erstellen eines Agents konfigurieren Sie drei Kernparameter:

    ```typescript
    const agent = new ClaudeAgent({
    model: 'claude-sonnet-4-20250514',
    tools: ['Read', 'Write', 'Edit', 'Bash'],
    permissionMode: 'acceptEdits'
    });
    ```

    • model: Claude-Modellversion wählen
    • tools: Verfügbare Tools des Agents festlegen
    • permissionMode: Berechtigungsmodus
  3. 3

    Step 3: Aufgabe ausführen und Ergebnis abrufen

    Rufen Sie die run-Methode auf, um eine Aufgabe auszuführen:

    ```typescript
    const result = await agent.run('auth.ts refaktorisieren');
    ```

    Empfehlung: Fehlerbehandlung und Logging ergänzen.
  4. 4

    Step 4: Schutzmaßnahmen konfigurieren

    In Produktionsumgebungen sind Schutzmaßnahmen Pflicht:

    • maxIterations: Maximale Iterationszahl begrenzen (Empfehlung: 20)
    • timeout: Zeitlimit setzen (Empfehlung: 5 Minuten)
    • systemPrompt: Verhaltensgrenzen definieren
    • permissionMode: Bei sensiblen Operationen Modus 'interactive' verwenden

FAQ

Wie wähle ich zwischen ReAct, Plan-and-Execute und Multi-Agent?
Je nach Aufgabencharakter: ReAct eignet sich für unsichere Schrittfolgen und dynamische Entscheidungen (z. B. Kundenservice-Q&A); Plan-and-Execute für vorhersehbare Schritte und stabile Ausgaben (z. B. Berichtserstellung); Multi-Agent für komplexe Aufgaben mit mehreren Fachdisziplinen (z. B. Softwareentwicklungs-Pipeline).
Warum empfiehlt Azure, Group-Chat-Agents auf maximal drei zu begrenzen?
Zu viele Group-Chat-Agents führen zu zwei Problemen: Erstens konvergiert die Diskussion schwer – mehrere Agents können in endlosen Debatten stecken bleiben. Zweitens steigen Debugging-Kosten exponentiell, weil Zustandssynchronisation und Nachrichtenweitergabe extrem komplex werden. Drei Agents (z. B. Moderator plus zwei Gegenpositionen) decken die meisten diskussionsbasierten Entscheidungsszenarien ab.
LangChain oder AutoGen/CrewAI – wie entscheide ich?
Für die meisten Szenarien reicht LangChain: reiche Tool-Integration, ausgereifte ReAct-Implementierung, starke Community. AutoGen oder CrewAI lohnen sich erst, wenn Sie Multi-Agent-Kollaboration wirklich brauchen. AutoGen unterstützt Human-in-the-loop – gut für manuelle Eingriffe. CrewAI hat eine schlankere API – ideal für schnelle Prototypen.
Für welche Szenarien eignet sich das Claude Agent SDK?
Das Claude Agent SDK ist das offizielle Anthropic-Tool und passt besonders zu drei Fällen: Erstens, wenn Claude Ihr Hauptmodell ist – tiefe Integration. Zweitens bei codebezogenen Aufgaben – eingebaute Datei-Lese-/Schreib- und Code-Edit-Funktionen. Drittens, wenn Sie feingranulare Berechtigungskontrolle brauchen – permissionMode steuert Operationen stufenweise.
Wie vermeide ich Endlosschleifen beim Agent?
Drei zentrale Schutzmaßnahmen: Erstens maxIterations setzen (Empfehlung 10–20), danach erzwungen stoppen. Zweitens timeout (Empfehlung 5 Minuten), bei Überschreitung abbrechen. Drittens im systemPrompt klare Abbruchbedingungen definieren – wann der Agent aufgeben soll. Mein erster ReAct-Agent lief eine ganze Nacht, weil ich das nicht gesetzt hatte.

12 Min. Lesezeit · Veröffentlicht am: 21. März 2026 · Aktualisiert am: 9. Juli 2026

Kommentare

Melde dich mit GitHub an, um einen Kommentar zu hinterlassen

Easton BlogEaston Blog