SwarmCore

Multi-agent orchestration for Python. Compose AI agents into sequential and parallel flows with automatic context sharing.

Installation

pip install swarmcore

Quickstart

import asyncio
from swarmcore import Swarm, researcher, writer

result = asyncio.run(Swarm(flow=researcher() >> writer()).run("AI agent trends in 2025"))
print(result.output)

The default model is anthropic/claude-opus-4-6 (requires ANTHROPIC_API_KEY). To use Google Gemini's free tier instead:

flow = researcher(model="gemini/gemini-2.5-flash") >> writer(model="gemini/gemini-2.5-flash")
result = asyncio.run(Swarm(flow=flow).run("AI agent trends in 2025"))

Features

• Agent factories — pre-built researcher, analyst, writer, editor, and summarizer with sensible defaults
• Flow operators — >> for sequential, | for parallel, compose freely
• Automatic context — each agent receives prior outputs automatically, with smart summarization
• Any model — works with any LiteLLM-compatible provider (Anthropic, OpenAI, Gemini, Groq, Ollama, etc.)
• Tool calling — pass plain Python functions as tools, sync or async
• Observability — built-in console_hooks() for live progress, or wire up custom event hooks

Agent factories

Pre-built factories for common workflow roles. Zero-config defaults for prototyping, full override for production.

from swarmcore import researcher, analyst, writer, editor, summarizer

Every parameter is optional and keyword-only:

# Zero-config
researcher()

# Fine-tuned
researcher(
    name="market_researcher",
    model="openai/gpt-4o",
    instructions="Focus on TAM and competitive landscape.",
    tools=[my_custom_search],   # replaces default search_web
    timeout=30.0,
)

Or build agents from scratch:

from swarmcore import Agent

agent = Agent(name="researcher", instructions="Research the topic.", model="anthropic/claude-opus-4-6")

Flows

>> for sequential, | for parallel:

researcher() >> writer()                            # sequential
(analyst() | writer()) >> editor()                  # parallel then sequential
researcher() >> (analyst() | writer()) >> editor()  # mixed

Parallel groups can contain multi-step sub-flows:

(researcher >> analyst) | (critic >> editor) >> writer

researcher ──► analyst ──┐
                         ├──► writer
critic ──► editor ───────┘

Each branch runs its steps sequentially; branches run concurrently via asyncio.gather.

Functional API:

from swarmcore import chain, parallel

chain(planner, parallel(researcher, critic), writer)

Context management

Each agent in a flow receives context from prior steps automatically:

• Previous step — full output
• Earlier steps — summaries only
• On demand — agents call expand_context to retrieve any prior agent's full output

agent_1 >> agent_2 >> ... >> agent_10

agent_10 sees: agents 1-8 [SUMMARIES] + agent_9 [FULL]
               (can expand any earlier agent on demand)

Agents produce summaries via <summary> tags in their output. If omitted, the full output is used as both.

Tools

Tools are plain Python functions. Type hints and docstrings are converted to tool schemas automatically.

def search_web(query: str) -> str:
    """Search the web for information."""
    return results

agent = Agent(name="researcher", instructions="...", tools=[search_web])

Sync and async functions both work.

Models

Any LiteLLM-compatible model. Set the API key for your provider:

export ANTHROPIC_API_KEY=sk-...    # for anthropic/ models (default)
export GEMINI_API_KEY=...          # for gemini/ models (free tier available)
export OPENAI_API_KEY=sk-...       # for openai/ models

researcher(model="anthropic/claude-opus-4-6")    # default
researcher(model="gemini/gemini-2.5-flash")      # free tier, no credit card needed
researcher(model="openai/gpt-4o")
researcher(model="groq/llama-3.1-8b-instant")
researcher(model="ollama/llama3")                # local, no API key needed

Example: single agent vs. multi-agent flow

Both outputs below use the same model and prompt — the difference is orchestration.

Evaluate the opportunity for launching an AI-powered personal nutrition coach app that uses computer vision to analyze meals and provides real-time dietary recommendations.

API reference

Agent(name, instructions, model, tools, timeout, max_retries, max_turns)

Swarm(flow, hooks, timeout, max_retries)

SwarmResult

AgentResult

License

MIT