Agency Swarm: Python-Framework für anpassbare Multi-Agenten-Systeme

Einführung in Agency Swarm

In der sich schnell entwickelnden Welt der künstlichen Intelligenz gewinnen Multi-Agenten-Systeme zunehmend an Bedeutung. Sie ermöglichen es, komplexe Aufgaben durch die Zusammenarbeit spezialisierter KI-Agenten effizienter zu lösen. Agency Swarm ist ein innovatives Open-Source-Python-Framework, das genau diese kollaborative Intelligenz fördert. Entwickelt von Arsenii Shatokhin (VRSEN), zielt Agency Swarm darauf ab, die Erstellung und Orchestrierung von KI-Agenturen zu vereinfachen, indem es eine intuitive Struktur für die Definition von Agentenrollen, Kommunikationsflüssen und Tool-Sharing bietet. Das Framework basiert auf dem neuesten OpenAI Agents SDK / Responses API und erweitert dessen Funktionen, um eine robuste und produktionsreife Lösung für die Entwicklung intelligenter Agenten-Schwärme zu schaffen.

Was ist Agency Swarm? Kernkonzept und Architektur

Agency Swarm ist mehr als nur ein Framework; es ist eine Philosophie zur Automatisierung, die sich an realen Organisationsstrukturen orientiert. Das Kernkonzept besteht darin, dass komplexe Probleme durch die Aufteilung in kleinere, handhabbare Aufgaben gelöst werden, die von spezialisierten KI-Agenten in einer kollaborativen Umgebung bearbeitet werden. Jeder Agent innerhalb eines Agency Swarm hat eine klar definierte Rolle, spezifische Anweisungen und Zugriff auf eine Reihe von Tools, die es ihm ermöglichen, seine Aufgaben effektiv zu erfüllen.

Die Architektur von Agency Swarm ist modular und leichtgewichtig, was eine hohe Flexibilität und Anpassbarkeit gewährleistet. Es nutzt das OpenAI Agents SDK als Fundament und bietet eine zusätzliche Orchestrierungsebene, die die Kommunikation und Koordination zwischen den Agenten steuert. Diese Orchestrierung erfolgt über explizit definierte Kommunikationsflüsse, die festlegen, welche Agenten miteinander interagieren dürfen und wie diese Interaktionen ablaufen. Dies verhindert Chaos und sorgt für eine zielgerichtete Zusammenarbeit. Durch die Verwendung von Pydantic-Modellen für die Tool-Definition und die Implementierung von Guardrails wird zudem eine robuste Fehlerkorrektur und Typvalidierung gewährleistet, was die Zuverlässigkeit des Gesamtsystems erheblich steigert.

Hauptfeatures und Alleinstellungsmerkmale

Agency Swarm zeichnet sich durch eine Reihe von Funktionen aus, die es von anderen Multi-Agenten-Frameworks abheben:

• Anpassbare Agentenrollen: Entwickler können spezifische Rollen wie CEO, virtueller Assistent oder Entwickler definieren und deren Funktionalitäten präzise anpassen. Dies ermöglicht eine hohe Spezialisierung und Effizienz innerhalb des Agenten-Schwarms.
• Volle Kontrolle über Prompts: Im Gegensatz zu vielen anderen Frameworks, die vordefinierte Prompts verwenden, bietet Agency Swarm vollständige Kontrolle über die Anweisungen der Agenten. Dies vermeidet Konflikte und ermöglicht eine exakte Steuerung des Agentenverhaltens.
• Robuste Fehlerkorrektur: Durch Pydantic-basierte Typvalidierung und integrierte Guardrails werden Halluzinationen und Fehler in der Agentenkommunikation und -ausführung minimiert, was die Zuverlässigkeit des Systems erhöht.
• Effiziente und gerichtete Kommunikation: Agenten kommunizieren über ein dediziertes send_message-Tool, wobei die Interaktionen durch explizite communication_flows gesteuert werden. Dies fördert eine strukturierte und zielgerichtete Zusammenarbeit.
• Benutzerdefinierte Python-Tools: Das Framework ermöglicht die einfache Erstellung und Integration benutzerdefinierter Python-basierter Tools, wodurch Agenten neue Fähigkeiten erhalten und mit externen APIs verbunden werden können.
• Produktionsreife und einfache Bereitstellung: Agency Swarm ist von Grund auf für den Einsatz in Produktionsumgebungen konzipiert. Es bietet spezielle Callback-Funktionen und Open-Source-Vorlagen, die eine einfache Bereitstellung ermöglichen.
• Flexible Zustandspersistenz: Die Möglichkeit, Konversationsverläufe über load_threads_callback und save_threads_callback zu verwalten, gewährleistet die Persistenz von Agenteninteraktionen über verschiedene Sitzungen hinweg.

Installation und Erste Schritte

Der Einstieg in Agency Swarm ist dank der klaren Dokumentation und der einfachen Installationsprozedur unkompliziert.

Installation

Die Installation erfolgt über pip, den Python-Paketmanager:

pip install -U agency-swarm

pip install -U agency-swarm

Erste Schritte: Ein Beispiel-Workflow

Um ein Multi-Agenten-System mit Agency Swarm zu erstellen, sind folgende grundlegende Schritte erforderlich:

1. OpenAI API-Schlüssel setzen: Der API-Schlüssel muss als Umgebungsvariable OPENAI_API_KEY gesetzt werden. Dies kann entweder in einer .env-Datei oder direkt in der Shell erfolgen:

   shell

   export OPENAI_API_KEY="YOUR_API_KEY"
   

   export OPENAI_API_KEY="YOUR_API_KEY"
   

2. Tools erstellen: Definieren Sie die Tools, die Ihre Agenten verwenden sollen. Dies kann entweder mit dem @function_tool-Decorator oder durch Erweitern der BaseTool-Klasse geschehen. Tools sind entscheidend, um Agenten mit spezifischen Fähigkeiten auszustatten und sie mit externen Diensten zu verbinden.

   python

   from agency_swarm import function_tool
   
   @function_tool
   def my_custom_tool(example_field: str) -> str:
       """A brief description of what the custom tool does."""
       return f"Result: {example_field}"
   

   from agency_swarm import function_tool
   
   @function_tool
   def my_custom_tool(example_field: str) -> str:
       """A brief description of what the custom tool does."""
       return f"Result: {example_field}"
   

3. Agentenrollen definieren: Erstellen Sie Agenteninstanzen und definieren Sie deren Namen, Beschreibungen, Anweisungen und die ihnen zugewiesenen Tools. Jeder Agent sollte eine klare Aufgabe und Persönlichkeit haben.

   python

   from agency_swarm import Agent, ModelSettings
   
   ceo = Agent(
       name="CEO",
       description="Responsible for client communication, task planning and management.",
       instructions="You must converse with other agents to ensure complete task execution.",
       tools=[my_custom_tool],
       model="gpt-5.2",
       model_settings=ModelSettings(
           max_tokens=25000,
       ),
   )
   

   from agency_swarm import Agent, ModelSettings
   
   ceo = Agent(
       name="CEO",
       description="Responsible for client communication, task planning and management.",
       instructions="You must converse with other agents to ensure complete task execution.",
       tools=[my_custom_tool],
       model="gpt-5.2",
       model_settings=ModelSettings(
           max_tokens=25000,
       ),
   )
   

4. Agenten-Kommunikationsflüsse definieren: Legen Sie fest, wie die Agenten miteinander kommunizieren dürfen. Agency Swarm verwendet gerichtete Kommunikationsflüsse, die mit dem >-Operator definiert werden. Dies stellt sicher, dass die Kommunikation strukturiert und kontrolliert abläuft.

   python

   from agency_swarm import Agency
   from Developer import Developer
   from VirtualAssistant import VirtualAssistant
   
   dev = Developer()
   va = VirtualAssistant()
   
   agency = Agency(
       ceo,
       communication_flows=[
           ceo > dev,
           ceo > va,
           dev > va
       ],
       shared_instructions=\'agency_manifesto.md\',
   )
   

   from agency_swarm import Agency
   from Developer import Developer
   from VirtualAssistant import VirtualAssistant
   
   dev = Developer()
   va = VirtualAssistant()
   
   agency = Agency(
       ceo,
       communication_flows=[
           ceo > dev,
           ceo > va,
           dev > va
       ],
       shared_instructions=\'agency_manifesto.md\',
   )
   

5. Demo ausführen: Nach der Definition der Agenten und Kommunikationsflüsse können Sie Ihr Multi-Agenten-System in verschiedenen Modi ausführen, z.B. über eine Web-Benutzeroberfläche, im Terminal oder programmatisch.

   • Web UI: agency.copilot_demo()
   • Terminal: agency.terminal_demo()
   • Programmatisch (async):
     python

     import asyncio
     
     async def main():
         resp = await agency.get_response("Create a project skeleton.")
         print(resp.final_output)
     
     asyncio.run(main())
     

     import asyncio
     
     async def main():
         resp = await agency.get_response("Create a project skeleton.")
         print(resp.final_output)
     
     asyncio.run(main())
     

Typischer Anwendungsfall: Softwareentwicklung mit einem Agenten-Schwarm

Ein hervorragendes Beispiel für den Einsatz von Agency Swarm ist die Automatisierung von Softwareentwicklungsprozessen. Stellen Sie sich eine "Softwareentwicklungs-Agentur" vor, die aus mehreren spezialisierten KI-Agenten besteht:

1. CEO-Agent: Verantwortlich für die Kommunikation mit dem Benutzer, die Analyse der Anforderungen, die Aufteilung des Projekts in kleinere Aufgaben und die Delegation an die Entwicklungsteams.
2. Entwickler-Agent: Erhält Aufgaben vom CEO, schreibt Code, erstellt Dateien, führt Tests durch und kommuniziert bei Bedarf mit anderen Agenten.
3. Qualitätssicherungs-Agent: Überprüft den vom Entwickler-Agenten erstellten Code, identifiziert Fehler und schlägt Verbesserungen vor.
4. DevOps-Agent: Kümmert sich um die Bereitstellung der Anwendung und die Verwaltung der Infrastruktur.

Workflow-Beschreibung:

1. Anforderungsanalyse und Planung: Der CEO-Agent empfängt eine Anforderung vom Benutzer (z.B. "Erstelle eine einfache Webanwendung zur Aufgabenverwaltung"). Er analysiert die Anforderung, erstellt einen Projektplan und delegiert die ersten Entwicklungsaufgaben an den Entwickler-Agenten.
2. Entwicklung und Iteration: Der Entwickler-Agent beginnt mit der Implementierung der zugewiesenen Aufgaben. Er nutzt seine Tools, um Code zu schreiben und Tests durchzuführen. Bei Unsicherheiten oder Problemen kann er den CEO-Agenten um Klärung bitten. Nach Abschluss eines Moduls übergibt er es an den Qualitätssicherungs-Agenten.
3. Qualitätssicherung und Feedback: Der Qualitätssicherungs-Agent führt automatisierte Tests durch und überprüft den Code auf Fehler, Sicherheitslücken und die Einhaltung von Best Practices. Er sendet detailliertes Feedback an den Entwickler-Agenten, der die notwendigen Korrekturen vornimmt. Dieser Zyklus wiederholt sich, bis das Modul den Qualitätsstandards entspricht.
4. Bereitstellung: Sobald alle Module entwickelt und getestet wurden, koordiniert der CEO-Agent mit dem DevOps-Agenten die Bereitstellung der Anwendung in einer Staging- oder Produktionsumgebung.
5. Monitoring und Wartung: Nach der Bereitstellung überwacht der DevOps-Agent die Anwendung und meldet eventuelle Probleme an den CEO-Agenten, der dann weitere Maßnahmen einleitet.

Dieser Workflow demonstriert die Leistungsfähigkeit von Agency Swarm, komplexe Softwareentwicklungsprojekte durch die orchestrierte Zusammenarbeit spezialisierter KI-Agenten zu managen und zu automatisieren. Die klare Rollenverteilung und die kontrollierten Kommunikationsflüsse sind entscheidend für die Effizienz und Qualität des Ergebnisses.

Vor- und Nachteile

Vorteile

• Hohe Anpassbarkeit: Volle Kontrolle über Agentenrollen, Prompts und Kommunikationsflüsse ermöglicht eine präzise Anpassung an spezifische Anwendungsfälle.
• Robuste Fehlerkorrektur: Pydantic-basierte Typvalidierung und Guardrails verhindern Halluzinationen und erhöhen die Zuverlässigkeit der Agenteninteraktionen.
• Produktionsreife: Das Framework ist auf Stabilität und einfache Bereitstellung in realen Produktionsumgebungen ausgelegt.
• Effiziente Kollaboration: Gerichtete Kommunikationsflüsse fördern eine strukturierte und zielgerichtete Zusammenarbeit zwischen den Agenten.
• Breite Modellunterstützung: Durch die Integration mit LiteLLM SDK werden über ein Dutzend verschiedene Modelle unterstützt, was Flexibilität bei der Wahl des zugrunde liegenden Sprachmodells bietet.

Nachteile

• Lernkurve: Die hohe Flexibilität und die Notwendigkeit, Kommunikationsflüsse und Agentenrollen detailliert zu definieren, können für Einsteiger eine gewisse Lernkurve darstellen.
• Abhängigkeit von OpenAI SDK: Obwohl das Framework erweiterbar ist, basiert es stark auf dem OpenAI Agents SDK, was eine gewisse Abhängigkeit von der OpenAI-Plattform mit sich bringt.
• Komplexität bei großen Agenturen: Bei sehr großen und komplexen Agenturen mit vielen Agenten und Interaktionen könnte die Verwaltung der Kommunikationsflüsse und die Fehlerbehebung anspruchsvoll werden.
• Ressourcenverbrauch: Der Betrieb mehrerer spezialisierter Agenten, insbesondere mit großen Sprachmodellen, kann ressourcenintensiv sein und entsprechende Hardware oder Cloud-Ressourcen erfordern.

Vergleich zu ähnlichen Systemen

Agency Swarm positioniert sich im Bereich der Multi-Agenten-Frameworks neben etablierten Lösungen wie AutoGen und CrewAI. Der Hauptunterschied liegt in der Philosophie und dem Designansatz:

Zusammenfassend lässt sich sagen:

• Agency Swarm ist ideal für reale, geschäftsorientierte Anwendungsfälle, die eine hohe Kontrolle, Zuverlässigkeit und einfache Bereitstellung erfordern.
• AutoGen eignet sich hervorragend für Forschung, Experimente und neuartige KI-Anwendungen.
• CrewAI ist besser geeignet für die lokale Entwicklung und Experimente mit Open-Source-Modellen.

Für wen ist das System geeignet? (Zielgruppe)

Agency Swarm richtet sich primär an Entwickler, KI-Ingenieure und Unternehmen, die komplexe Multi-Agenten-Systeme für reale, geschäftsorientierte Anwendungsfälle entwickeln möchten. Die Zielgruppe profitiert besonders von der hohen Anpassbarkeit, der robusten Fehlerkorrektur und der Produktionsreife des Frameworks. Es ist ideal für Teams, die Wert auf präzise Kontrolle über das Agentenverhalten, effiziente Kommunikation und Skalierbarkeit legen, um anspruchsvolle Automatisierungsaufgaben zu bewältigen.

GitHub Informationen

• GitHub Stars: 4k (Stand 01.03.2026)
• Lizenz: MIT License
• Programmiersprache: Python (hauptsächlich)
• Offizielle Dokumentations-URL: https://agency-swarm.ai/
• GitHub-URL: https://github.com/VRSEN/agency-swarm

Fazit

Agency Swarm bietet eine überzeugende Lösung für die Entwicklung und Orchestrierung von Multi-Agenten-Systemen, insbesondere für geschäftliche Anwendungen. Die Kombination aus Flexibilität, Zuverlässigkeit und einfacher Bereitstellung macht es zu einem wertvollen Werkzeug für Entwickler, die das volle Potenzial kollaborativer KI-Agenten ausschöpfen möchten. Mit seiner klaren Architektur und dem Fokus auf kontrollierte Kommunikation setzt es neue Maßstäbe in der Entwicklung intelligenter Agenturen.