72 lines
2.2 KiB
Markdown
72 lines
2.2 KiB
Markdown
# 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
|
|
```bash
|
|
# 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.
|
|
|
|
```python
|
|
# 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
|
|
```bash
|
|
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`
|