How Codrea Works
A technical deep dive into the agent orchestration platform. Understand the core concepts, architecture, and how to build AI workflows.
The building blocks
Five core entities that power the orchestration engine
Task
The "Slack room" where agents coordinate. Represents a user's high-level goal.
Task(
name="Build auth",
root_agent=cto
)
Run
A unit of work. Both an execution record and work assignment. Can be delegated.
queued → in_progress
→ completed | failed
Agent
An AI persona with specific capabilities, tools, and LLM configuration.
tools=["read_file",
"write_file",
"create_run"]
Executor
Remote worker that executes client-side tools. Connects via WebSocket.
WebSocket bidirectional
Project-scoped access
Workflow
Markdown instructions that agents follow. Versioned for reproducibility.
WorkflowVersion
Referenced by Tasks
Two-Level Messaging
TaskMessage (shared) vs Message (run-private). Prevents context pollution.
Message: run-private
Three-part system
Create tasks, view conversations, receive SSE streams
Python/Node worker • Execute file ops, shell commands • Project-scoped
SDLC orchestration in action
How a "Build authentication" task flows through the system
User creates Task
User submits "Build JWT authentication for FastAPI"
Task created with root_agent=CTO, available_agents=[CTO, Architect, Developer, Tester]
CTO Agent analyzes
Initial Run created for CTO agent
CTO reads task, understands scope, decides to delegate to Architect first
CTO delegates via create_run
CTO uses create_run tool to assign work to Architect
New Run created: agent=Architect, title="Design auth architecture"
Architect designs
Architect reads codebase via Executor, creates design
Private Messages: read_file calls, analysis. TaskMessage: "I've designed the auth flow"
Developer implements
Developer Run receives design from TaskMessage history
Writes code via Executor (write_file), tests locally. TaskMessage: "Implementation complete"
Connect your environment
Connect Executor
Install the executor on your dev machine or CI:
pip install codrea-executor
# Connect
codrea connect --key ek_xxx...
Configure LLM Providers
Add your API keys for any supported provider:
providers:
- anthropic: $ANTHROPIC_KEY
- openai: $OPENAI_KEY
- gemini: $GOOGLE_KEY
Developer-friendly interface
from codrea import Client
client = Client(api_key="...")
# Create a task
task = client.tasks.create(
name="Build authentication",
description="Implement JWT auth for FastAPI",
root_agent="cto",
available_agents=["cto", "architect", "developer"],
project_id="proj_123",
)
# Stream updates
for event in client.tasks.stream(task.id):
if event.type == "task_message":
print(f"{event.agent}: {event.content}")
elif event.type == "run_completed":
print(f"Run {event.run_id} completed")Ready to build?
Join our design partner program to get early access and shape the platform.