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 Szenario | Empfohlene Ebene | Begründung |
|---|---|---|
| Einfache Q&A, Textverarbeitung | Direkter Modellaufruf | Reicht aus – kein Over-Engineering |
| Datenbank, API-Aufrufe nötig | Single Agent + Tools | Klassische Lösung, stabil |
| Aufgabe zerlegbar, Schritte unsicher | Single Agent + Tools (ReAct) | Agent plant Schritte selbst |
| Mehrere Fachrollen nötig | Multi-Agent-Orchestrierung | Vorsichtig – 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?“
- Thought: Ich muss zuerst das Wetter für morgen in Peking abfragen
- Action: Tool
get_weatheraufrufen, Parametercity: "Peking" - Observation: Morgen bewölkt, 18–25°C, 10 % Niederschlagswahrscheinlichkeit
- Thought: Temperatur angenehm, wenig Regen – geeignet für Outdoor-Sport
- 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:
| Vorteile | Nachteile |
|---|---|
| Hohe Flexibilität bei dynamischen Aufgaben | Kann in Endlosschleifen geraten |
| Transparenter Reasoning-Prozess, gut debuggbar | Höhere Kosten pro Aufruf |
| Keine vordefinierten Schritte nötig | Begrenzte 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:
| Vorteile | Nachteile |
|---|---|
| Stabile Ausführung, kontrollierbare Schritte | Plan nach Erstellung unflexibel |
| Gut für deterministische Aufgaben | Schwach bei stark dynamischer Umgebung |
| Einfaches Monitoring und Abbrechen | Planqualitä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
| Muster | Einsatz | Komplexität | Hauptrisiko |
|---|---|---|---|
| Sequential | Pipeline-Aufgaben | Niedrig | Blockierung durch Schrittabhängigkeiten |
| Concurrent | Parallele Multi-Perspektiven-Analyse | Mittel | Konflikte brauchen Schiedsmechanismus |
| Group Chat | Mehrstufige Diskussionsentscheidungen | Hoch | Keine Konvergenz, endlose Debatten |
| Handoff | Dynamische fachliche Übergabe | Mittel | Zyklen, Deadlock bei Übergabe |
| Magentic | Vielfältige Aufgabentypen | Hoch | Komplexe 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
| Framework | Kernposition | Stärken | Einsatz |
|---|---|---|---|
| LangChain | Allgemeines Agent-Framework | Reiche Tool-Integration, ausgereiftes ReAct | Schnelle Prototypen, Produktion, viele Tool-Integrationen |
| AutoGen | Multi-Agent-Kollaboration | Dialogische Zusammenarbeit, Human-in-the-loop | Komplexe Multi-Agent-Systeme, manuelle Eingriffe |
| CrewAI | Rollenspiel-Kollaboration | Schlanke API, intuitive Konzepte | Team-Simulation, klare Rollenverteilung |
| Claude Agent SDK | Claude-nativ | Code-Verständnis, Dateioperationen, tiefe Claude-Integration | Claude-Ö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
permissionModefür Berechtigungskontrolle- Wenn Claude Ihr Hauptmodell ist: erste Wahl
4.3 Auswahl-Leitfaden
Stellen Sie sich diese Fragen:
-
Welches Modell ist Ihr Hauptmodell?
- Claude → Claude Agent SDK bevorzugen
- OpenAI → LangChain-Ökosystem reifer
- Multi-Modell → LangChain oder AutoGen
-
Wie komplex ist die Aufgabe?
- Single Agent + Tools → LangChain reicht
- Multi-Agent-Kollaboration → AutoGen oder CrewAI
- Codebezogene Aufgaben → Claude Agent SDK
-
Welcher Tech-Stack im Team?
- Python-lastig → alle Frameworks unterstützt
- TypeScript-lastig → LangChain und Claude Agent SDK stärker
-
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 lesenWrite: Neue Datei anlegenEdit: Bestehende Datei bearbeitenBash: Shell-Befehle ausführenGlob: Dateimuster-MatchingGrep: 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
- Iterationen begrenzen: Endlosschleifen vermeiden
- Timeout setzen: Fallback für lange Läufe
- Berechtigungen staffeln: Sensibles mit
interactive - Backup: Wichtige Dateien vor Änderung sichern
- 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
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
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
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
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?
Warum empfiehlt Azure, Group-Chat-Agents auf maximal drei zu begrenzen?
LangChain oder AutoGen/CrewAI – wie entscheide ich?
Für welche Szenarien eignet sich das Claude Agent SDK?
Wie vermeide ich Endlosschleifen beim Agent?
12 Min. Lesezeit · Veröffentlicht am: 21. März 2026 · Aktualisiert am: 9. Juli 2026
AI Agent Engineering Guide
Wenn du über die Suche hier gelandet bist, kommst du am schnellsten weiter, indem du zum vorherigen oder nächsten Beitrag dieser Serie springst.
Vorheriger
Agent Sandbox aufbauen: Vollständiger Leitfaden für sichere KI-Codeausführung
Detaillierter Leitfaden zum Aufbau einer AI-Agent-Sandbox: Technologievergleich von gVisor bis Firecracker, Deployment von lokaler Entwicklung bis Kubernetes-Cluster
Teil 1 von 16
Nächster
Agent-Memory-System-Design: Von der Sitzung zum Langzeitgedächtnis
Agent-Memory-System von Grund auf: vier Gedächtnistypen, Fünf-Phasen-Pipeline, Mem0/Zep/LangMem-Vergleich und produktionsreife Kostenoptimierung
Teil 3 von 16
Ähnliche Beiträge
KI-Agent-Gedächtnisverwaltung: Langzeitgedächtnis und Wissens-Governance in der Praxis

KI-Agent-Gedächtnisverwaltung: Langzeitgedächtnis und Wissens-Governance in der Praxis
Agent Tool Calling in der Praxis: KI externe APIs und Dienste aufrufen lassen


Kommentare
Melde dich mit GitHub an, um einen Kommentar zu hinterlassen