SwarmKit SDK

Run terminal-based AI agents in secure sandboxes with built-in observability.

Repo: https://github.com/brandomagnani/swarmkit — cookbooks in cookbooks/, skills in skills/

SDK Choice

Both SDKs are functionally identical. Choose based on application language.

Quick Start

# TypeScript
npm install @swarmkit/sdk

# Python
pip install swarmkit

Core Concepts

1. SwarmKit (Single Agent)

For single-agent tasks with multi-turn conversations.

SwarmKit → run() → getOutputFiles()

Key capabilities:

• Agent configuration (type, model, reasoning effort)
• Skills (pdf, docx, pptx, etc.)
• Composio integrations (GitHub, Gmail, Slack, etc.)
• MCP servers for custom tools
• Structured output via schema
• Context/files upload, session management

2. Swarm (Parallel Agents)

For parallel processing with functional abstractions.

When to use:

• map: Batch processing (analyze 100 docs)
• filter: Quality gates (keep only critical items)
• reduce: Synthesis (combine into report)
• best_of: Quality (run 3 agents, pick best)

3. Pipeline (Chained Operations)

Preferred API for most workflows. Fluent, readable, reusable.

Pipeline → .map() → .filter() → .reduce() → .run()

Reusable across different data batches.

Pipeline vs standalone Swarm calls:

• Use Pipeline for chains (map → filter → reduce) - cleaner API
• Use Swarm.bestOf() only for standalone best-of-N on single item (not available as pipeline step)

Pipeline restrictions:

• best_of only available as option within .map({ bestOf }), not as standalone step
• .reduce() is terminal - no steps after

Authentication

API keys auto-resolve from environment variables.

Note: In Gateway mode, SWARMKIT_API_KEY is automatically injected into this sandbox by the parent SwarmKit process. The SDK picks it up from the environment—no manual configuration needed.

Gateway Mode

# .env
SWARMKIT_API_KEY=sk-...

SwarmKit().withAgent({ type: "claude", apiKey: SWARMKIT_API_KEY })

Included: E2B sandbox auto-provisioned, browser-use integrated, tracing at dashboard.evolvingmachines.ai

BYOK Mode

# .env
ANTHROPIC_API_KEY=sk-...   # or OPENAI_API_KEY, GEMINI_API_KEY
E2B_API_KEY=e2b_...

sandbox = E2BProvider({ apiKey: E2B_API_KEY })
SwarmKit().withAgent({ type: "claude", providerApiKey: ANTHROPIC_API_KEY }).withSandbox(sandbox)

Claude Max (OAuth)

claude --setup-token  # Run in terminal → receive token

# .env
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-...
E2B_API_KEY=e2b_...

SwarmKit().withAgent({ type: "claude", oauthToken: CLAUDE_CODE_OAUTH_TOKEN }).withSandbox(sandbox)

Full docs: See references/typescript.md or references/python.md

BYOK Mode: Set provider env vars (see Agent Types table) + E2B_API_KEY.

Agent Types

Workspace Structure

Agents run in sandboxes with this filesystem:

/home/user/workspace/
├── context/     # Input files (read-only)
├── scripts/     # Agent code
├── temp/        # Scratch space
└── output/      # Final deliverables

Structured Output

Provide a schema (Zod/JSON Schema for TS, Pydantic/dict for Python) and the agent writes output/result.json.

withSchema(schema) → run() → getOutputFiles() → { files, data, error }

Key Patterns

Skills + Composio + MCP hierarchy

.withSkills([...])           # Agent capabilities (browser-use included by default with Gateway)
.withComposio(userId, {...}) # 1000+ integrations
.withMcpServers({...})       # Custom tools (advanced)

Note: With SWARMKIT_API_KEY, browser-use is already integrated. Additional browser skills (dev-browser, agent-browser) are optional.

Streaming Events

Content events: agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update, plan

Session Management

run() → run() → run()     # Same session, maintains history
getSession() → save       # Persist session ID
setSession(id) → run()    # Reconnect later
pause() / resume()        # Suspend/reactivate billing
kill()                    # Destroy sandbox

Swarm Operations Detail

Input: FileMap

FileMap = { "path": content }  # path in context/, content is string or bytes

Items can be: single file, multiple files, or entire folders per worker.

Result Types

SwarmResult (from map, filter, best_of):

• status: 'success' | 'filtered' | 'error'
• data: Parsed schema or null
• files: Output files
• meta: Operation metadata

SwarmResultList (from map, filter):

• .success / .filtered / .error accessors

ReduceResult (from reduce):

• Single result with data, files, meta

Chaining

When chaining, result.json from previous step → data.json in next step's context.

Quality Options

verify: LLM-as-judge verifies output, retries with feedback

verify: { criteria: "...", maxAttempts: 3 }

bestOf: Run N candidates, judge picks best

bestOf: { n: 3, judgeCriteria: "..." }

retry: Auto-retry on error with backoff

retry: { maxAttempts: 3, backoffMs: 1000 }

Language-Specific Syntax

For complete syntax and examples:

• TypeScript: references/typescript.md
• Python: references/python.md