Multi-agent LLM orchestration framework. Ajan ekipleri tanımla, DAG tabanlı workflow'lara bağla, yerleşik doğrulama, yeniden deneme ve checkpoint/resume desteğiyle çalıştır.

Ajan → Tool → Workflow → Sonuç

---

Özellikler

• Çoklu LLM desteği — OpenAI, Anthropic, Gemini, Groq, Grok (xAI), Ollama
• DAG workflow motoru — sıralı, paralel ve koşullu dallar
• Araç sistemi — Gmail, Slack, web arama, dosya sistemi, paylaşımlı bellek
• Doğrulama & yeniden deneme — required_tools, output_must_contain, backoff
• İnsan onayı — HumanPauseNode ile workflow'u durdur, karar bekle
• Checkpoint / resume — kesintiden kaldığı yerden devam et
• MCP desteği — Model Context Protocol sunucularına bağlan

---

Kurulum

pip install -e .

# Gmail + Gemini (canlı örnekler için):
pip install -e ".[live]"

# Groq desteği:
pip install -e ".[groq]"

# Her şey:
pip install -e ".[all]"

Python 3.9+ gerektirir.

---

5 Dakikada Başla

import asyncio
from swarm import (
    TeamConfig, AgentConfig,
    Workflow, TaskNode,
    WorkflowRunner, TeamSession,
    PermissionLevel,
)

config = TeamConfig(
    agents=[
        AgentConfig(
            name="writer",
            model="gemini-2.0-flash",
            provider="gemini",
            api_key="YOUR_GEMINI_API_KEY",
        )
    ],
    default_permission_level=PermissionLevel.READ_ONLY,
)

async def main():
    session = TeamSession(config)
    await session.initialize()

    workflow = Workflow(
        name="hello",
        nodes=[
            TaskNode(
                id="greet",
                title="Selamlama yaz",
                description="Bir geliştirici için tek cümlelik selamlama yaz.",
                assignee="writer",
            )
        ],
    )

    result = await WorkflowRunner(session=session).run(workflow)
    print(result.results["greet"])

asyncio.run(main())

---

Temel Kavramlar

AgentConfig

Her ajan bir LLM modeline, sistem prompt'una ve araç listesine eşlenir.

AgentConfig(
    name="analyst",
    model="gemini-2.0-flash",      # model adı
    provider="gemini",              # openai | anthropic | gemini | groq | grok | ollama
    api_key="...",
    system_prompt="Sen bir veri analistisin.",
    tools=["gmail_search", "memory_write"],
    permission_level=PermissionLevel.NETWORK,
    max_turns=30,
)

Workflow & Node Türleri

Workflow, isteğe bağlı depends_on kenarlarıyla DAG oluşturan node listesidir.

Node	Amaç
TaskNode	Bir ajana atanan iş birimi
GateNode	Sonuçları değerlendirip bir dala yönlendirir
LoopNode	Çıkış koşulu sağlanana kadar tekrarlar
LoopEndNode	Döngü gövdesinin sonu
HumanPauseNode	Workflow'u durdurur, dış resume() çağrısı bekler

Paralel Yürütme

depends_on ile bağımlılık olmayan node'lar otomatik olarak paralel çalışır:

Workflow(nodes=[
    TaskNode(id="collector", ...),
    TaskNode(id="stats",    depends_on=["collector"], ...),   # \
    TaskNode(id="priority", depends_on=["collector"], ...),   # / paralel
    TaskNode(id="report",   depends_on=["stats", "priority"], ...),
])

Araç Sistemi

Araçlar JSON Schema ile tanımlanır; model hangi aracı ne zaman çağıracağına kendisi karar verir.

AgentConfig(
    tools=["gmail_read_unread", "gmail_add_label", "memory_write"],
    ...
)

Yerleşik araçlar: memory_read, memory_write, bash, file_read, file_write, file_edit, grep

İletişim araçları: gmail_read_unread, gmail_search, gmail_send, gmail_send_reply, gmail_add_label, gmail_mark_read, slack_send_message

Web araçları: web_search, web_scrape, web_fetch

Paylaşımlı Bellek

Ajanlar memory_write / memory_read araçlarıyla birbirine veri aktarır:

# stats_agent yazdı:
memory_write(key="stats", value="Newsletter: 5, Billing: 3, ...")

# report_agent okudu:
memory_read(key="stats_agent/stats")

Doğrulama

TaskNode(
    id="fetch",
    required_tools=["gmail_read_unread"],   # ajan bu aracı MUTLAKA çağırmalı
    output_must_contain=["Processed:"],     # çıktı bu metni içermeli
    required_tools_must_succeed=True,       # araç hatası = görev hatası
    max_retries=3,                          # doğrulama başarısızlığında tekrar dene
    retry_delay_ms=5000,                    # yeniden denemeler arası bekleme
)

Checkpoint / Resume

runner = WorkflowRunner(session=session, checkpoint_path="run.checkpoint.json")
result = await runner.run(workflow)
# Kesinti olursa aynı checkpoint_path ile tekrar çalıştır — tamamlanan node'lar atlanır
runner.clear_checkpoint()

İnsan Onayı

from swarm import HumanPauseNode

workflow = Workflow(nodes=[
    TaskNode(id="draft", ...),
    HumanPauseNode(
        id="review",
        depends_on=["draft"],
        message="Taslağı onaylıyor musunuz?",
        options=["onayla", "reddet"],
        timeout_seconds=300,
    ),
    TaskNode(id="send", depends_on=["review"], ...),
])

# Başka bir coroutine'den:
runner.resume("review", decision="onayla")

---

Desteklenen LLM Sağlayıcıları

Sağlayıcı	provider=	Tool Desteği	Notlar
Google Gemini	"gemini"	Native	Ücretsiz kota: 2.0-flash 1500/gün
Anthropic	"anthropic"	Native	Claude 3/4 serisi
OpenAI	"openai"	Native	GPT-4o, o1, o3-mini
Groq	"groq"	Native + repair	Llama, Kimi, Qwen
Grok (xAI)	"grok"	Native	Grok-3, Grok-2
Ollama	"ollama"	Native	Yerel modeller

---

Örnekler

Dosya	Ne gösteriyor
examples/quickstart.py	2 ajanlı doğrusal pipeline (araştır → yaz)
examples/01_content_pipeline.py	Yazar + editör pipeline
examples/02_api_team.py	API ekibi ile çok adımlı görev
examples/03_social_media_team.py	Paralel görevler, farklı ajanlar
examples/04_validation_demo.py	Doğrulama fazları demosu
examples/05_support_triage.py	Gate + insan onayı + yeniden gönderme
examples/06_gmail_labeler.py	Tek ajanlı Gmail etiketleyici, 60s polling
examples/07_gmail_digest.py	5 ajanlı paralel digest, SharedMemory

Demo modda (API anahtarı gerekmez):

python examples/06_gmail_labeler.py        # sahte verilerle
python examples/07_gmail_digest.py        # sahte verilerle

Canlı modda:

GEMINI_API_KEY=... GMAIL_SENDER=sen@gmail.com \
python examples/06_gmail_labeler.py --live

GEMINI_API_KEY=... GMAIL_SENDER=sen@gmail.com \
python examples/07_gmail_digest.py --live

---

Testler

source venv/bin/activate
pytest tests/ -v --tb=short

Tüm testler FakeAdapter kullanır — gerçek API çağrısı yapılmaz.

---

Proje Yapısı

swarm/
  agent/          # AgentRunner — tur döngüsü, araç çalıştırma, nudge
  llm/            # LLM adaptörleri (Gemini, OpenAI, Anthropic, Groq, Grok, Ollama)
  orchestrator/   # WorkflowRunner, Scheduler, Executor, retry mantığı
  permissions/    # PermissionLevel enum ve kontrol mekanizması
  task/           # TaskQueue, Workflow node türleri
  team/           # TeamSession — ajan kaydı, mesaj bus'ı
  tool/           # Araç sistemi (Gmail, Slack, web, dosya, bellek)
  types/          # Paylaşımlı Pydantic modeller
  workflows/      # Hazır workflow şablonları
  memory/         # SharedMemory

examples/         # Çalışan örnek scriptler
tests/            # Birim + entegrasyon testleri
docs/             # Detaylı dokümantasyon

---

Dokümantasyon

Doküman	İçerik
docs/concepts.md	Temel kavramlar — ajan, araç, workflow, bellek
docs/tools.md	Araç kataloğu ve yeni araç yazma rehberi
docs/architecture.md	Sistem mimarisi ve veri akışı
QUICKSTART.md	Gmail entegrasyonu dahil adım adım başlangıç