Agent Orchestra

Multi-agent system with Claude agents communicating via Slack. Each agent runs inside its own Docker container with the Claude Agent SDK.

Quick Start

# Start all services
docker-compose up -d

# Or for local development:
uv sync
cp .env.example .env  # Fill in ANTHROPIC_API_KEY, Slack tokens, Gitea tokens
uv run python -m orchestra.main

Architecture

Orchestrator: Lightweight service that routes Slack messages to agents via HTTP
Agent Containers: Each runs Claude SDK + HTTP API for receiving messages
Tools: Built-in (Read/Write/Bash run in container) + custom MCP tools
Permissions: PreToolUse hooks enforce agent-specific restrictions
Communication: Orchestrator → HTTP → Agent containers

Orchestrator (Slack listener) --HTTP--> Agent Containers (SDK + HTTP API)

Claude Agent SDK Usage

Each agent container runs ClaudeSDKClient for persistent conversations. The orchestrator communicates with agents via HTTP API.

# In agent container
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(options) as client:
    await client.query(message)
    async for msg in client.receive_response():
        process(msg)

Custom tools use @tool decorator and create_sdk_mcp_server().

Key Files

config/orchestra.yml - Global config (Slack, agent endpoints)
config/agents/*.yml - Agent definitions (tools, permissions, prompts)
src/orchestra/core/orchestrator.py - Slack listener, HTTP routing
src/orchestra/agent/agent.py - Agent service with SDK + HTTP API
src/orchestra/tools/ - Custom MCP tool implementations

Agent Permissions

Each agent has:

allowed_tools / disallowed_tools - Tool access
permissions.filesystem - Path restrictions
permissions.git - Branch push/merge restrictions

Enforced via PreToolUse hooks that check before execution.

Testing

uv run pytest
uv run pytest tests/test_agent.py -v

Common Tasks

Add agent: Create YAML in config/agents/, add to docker-compose
Add tool: Use @tool decorator in src/orchestra/tools/, register in server
Debug agent: Check container logs: docker logs agent-dev

2.2 KiB Raw Blame History