You've heard about AI agents. You've seen demos. Now you want to build an agent team for your organization.
This guide walks you through creating your first multi-agent system using Agent.ceo. By the end, you'll have a working team of agents that can communicate, delegate tasks, and work together.
Prerequisites:
- Basic familiarity with command line
- Docker installed on your machine
- An Anthropic API key (or other supported LLM provider)
Let's build.
What We're Building
A three-agent team for automated research and reporting:
+--------------+ +--------------+ +--------------+
| Coordinator |-->| Researcher |-->| Writer |
| Agent | | Agent | | Agent |
+--------------+ +--------------+ +--------------+
"Research AI trends "Search and "Compile into
and write report" analyze data" readable report"
Coordinator Agent: Receives requests, breaks them into tasks, delegates to specialists Researcher Agent: Searches for information, analyzes sources, extracts key insights Writer Agent: Takes research and produces polished reports
This pattern - coordinator plus specialists - scales to many use cases.
Step 1: Set Up Agent.ceo
Install Agent.ceo Lite
The fastest way to start is Agent.ceo Lite, our single-machine version:
# Download the quick-start script
curl -fsSL https://get.agent.ceo/lite | sh
# Or use Docker Compose directly
git clone https://github.com/genbrain-ai/agent-hub-lite.git
cd agent-hub-lite
docker-compose up -d
This starts:
- Agent Registry (port 8002) - Discovers and tracks agents
- NATS JetStream (port 4222) - Message bus for agent communication
- Dashboard (port 3000) - Visual interface for monitoring
Verify Installation
# Check that services are running
curl http://localhost:8002/health
# Should return: {"status": "healthy"}
# Check NATS
curl http://localhost:8222/healthz
# Should return: {"status": "ok"}
Step 2: Configure Your First Agent
Create the Coordinator Agent
Create a file called coordinator-agent.yaml:
# coordinator-agent.yaml
agent:
id: coordinator
name: "Task Coordinator"
description: "Coordinates research tasks and delegates to specialists"
# What this agent can do
skills:
- coordination
- task-planning
- delegation
# LLM configuration
model:
provider: anthropic
name: claude-3-5-sonnet-20241022
# System prompt that defines agent behavior
system_prompt: |
You are a Task Coordinator agent. Your job is to:
1. Receive research requests from users
2. Break complex requests into manageable tasks
3. Delegate tasks to specialist agents (researcher, writer)
4. Track progress and compile final results
When you receive a request:
- Analyze what information is needed
- Send research tasks to the "researcher" agent
- Once research is complete, send writing tasks to the "writer" agent
- Return the final report to the requester
Use the send_to_agent tool to communicate with other agents.
# Tools this agent can use
tools:
- send_to_agent
- get_agent_status
- track_task
Create the Researcher Agent
Create researcher-agent.yaml:
# researcher-agent.yaml
agent:
id: researcher
name: "Research Specialist"
description: "Searches for information and extracts insights"
skills:
- research
- web-search
- data-analysis
model:
provider: anthropic
name: claude-3-5-sonnet-20241022
system_prompt: |
You are a Research Specialist agent. Your job is to:
1. Receive research requests from the coordinator
2. Search for relevant information using available tools
3. Analyze and synthesize findings
4. Report back with structured insights
Format your research output as:
- Key findings (bullet points)
- Supporting data
- Sources used
- Confidence level (high/medium/low)
tools:
- web_search
- read_url
- send_to_agent
# MCP servers this agent can access
mcp_servers:
- brave-search
- fetch
Create the Writer Agent
Create writer-agent.yaml:
# writer-agent.yaml
agent:
id: writer
name: "Report Writer"
description: "Transforms research into polished reports"
skills:
- writing
- report-generation
- summarization
model:
provider: anthropic
name: claude-3-5-sonnet-20241022
system_prompt: |
You are a Report Writer agent. Your job is to:
1. Receive research data from the coordinator or researcher
2. Transform raw research into readable, well-structured reports
3. Ensure clarity, accuracy, and proper formatting
4. Return the completed report to the coordinator
Report format:
- Executive summary (2-3 sentences)
- Key findings (with headers)
- Detailed analysis
- Recommendations (if applicable)
- Sources
tools:
- send_to_agent
- format_markdown
Step 3: Deploy Your Agents
Register Agents with Agent.ceo
# Deploy the coordinator
agent-hub deploy coordinator-agent.yaml
# Deploy the researcher
agent-hub deploy researcher-agent.yaml
# Deploy the writer
agent-hub deploy writer-agent.yaml
Verify Deployment
# List all registered agents
agent-hub agents list
# Output:
# ID NAME STATUS SKILLS
# coordinator Task Coordinator healthy coordination, task-planning
# researcher Research Specialist healthy research, web-search
# writer Report Writer healthy writing, report-generation
Step 4: Test Agent Communication
Send a Test Request
Let's see if our agents can talk to each other:
# Send a simple test to the coordinator
agent-hub invoke coordinator "Say hello to the researcher agent"
You should see the coordinator:
- Receive your message
- Send a message to the researcher
- Get a response
- Reply to you
Watch the Message Flow
In another terminal, watch real-time messages:
agent-hub logs --follow
# Output:
# [2026-03-10T10:15:01Z] coordinator received: "Say hello to researcher"
# [2026-03-10T10:15:02Z] coordinator -> researcher: "Hello from coordinator"
# [2026-03-10T10:15:03Z] researcher -> coordinator: "Hello! Ready to research."
# [2026-03-10T10:15:04Z] coordinator response: "Researcher says: Ready to research."
Step 5: Run a Real Task
Research Request
Now let's try a real research task:
agent-hub invoke coordinator "Research the current state of AI agents in enterprise. Focus on adoption rates, common use cases, and challenges. Produce a brief report."
Sample Output
# AI Agents in Enterprise: 2026 State of Adoption
## Executive Summary
AI agent adoption in enterprise has grown 340% year-over-year, with customer
support and software development leading use cases. Key challenges remain
around governance and integration.
## Key Findings
### Adoption Rates
- 67% of Fortune 500 now using AI agents in some capacity
- Average deployment: 3-5 agents per organization
- Growth accelerating: 28% deployed in last 6 months
### Top Use Cases
1. **Customer Support** (78% of deployments)
2. **Software Development** (52%)
3. **Data Analysis** (48%)
4. **Operations Automation** (34%)
### Challenges
- Governance and compliance (cited by 72%)
- Integration with existing systems (61%)
- Model reliability (45%)
- Cost management (38%)
## Recommendations
Organizations should start with bounded use cases (customer support)
before expanding to more complex deployments.
## Sources
- Gartner AI Agent Report Q1 2026
- Forrester Enterprise AI Survey
- MIT Technology Review
*Report generated by Agent.ceo research team*
*Confidence: High*
Step 6: Customize and Extend
Add More Tools
Give your researcher agent access to more data sources:
# Updated researcher-agent.yaml
mcp_servers:
- brave-search # Web search
- fetch # URL reading
- postgres # Database queries
- notion # Company knowledge base
Add Specialized Agents
Need more capabilities? Add specialists:
# analyst-agent.yaml
agent:
id: analyst
name: "Data Analyst"
skills:
- data-analysis
- statistics
- visualization
mcp_servers:
- postgres
- python-runner # For data processing
Create Agent Hierarchies
For larger teams, add management layers:
+--------------+
| Director |
| Agent |
+------+-------+
|
+--------------+--------------+
| | |
+-------+-------++-----+-----++-------+-------+
| Coordinator ||Coordinator || Coordinator |
| (Research) || (Support) || (Dev) |
+-------+-------++-----+-----++-------+-------+
| | |
Specialists Specialists Specialists
Step 7: Production Considerations
Enable Observability
Add tracing to see exactly what agents do:
# In your agent config
observability:
tracing: true
metrics: true
log_level: info
Set Up Guardrails
Limit what agents can do:
guardrails:
rate_limits:
messages_per_minute: 60
api_calls_per_minute: 30
action_limits:
max_web_searches_per_task: 10
max_message_chain: 20
content_filters:
pii_detection: true
output_validation: true
Add Authentication
Secure agent communication:
security:
auth:
type: mtls
cert_path: /certs/agent.crt
key_path: /certs/agent.key
rbac:
coordinator:
can_invoke: [researcher, writer]
researcher:
can_invoke: [coordinator]
writer:
can_invoke: [coordinator]
Common Patterns
Pattern 1: Fan-Out / Fan-In
One coordinator sends tasks to multiple workers, then aggregates results:
+----------+
|Coordinator|
+----+-----+
+---------+---------+
v v v
[Worker1] [Worker2] [Worker3]
| | |
+---------+---------+
v
Aggregate
Use for: Parallel research, bulk processing, A/B comparisons
Pattern 2: Pipeline
Each agent processes and passes to the next:
[Input] -> [Stage 1] -> [Stage 2] -> [Stage 3] -> [Output]
Extract Analyze Format
Use for: Document processing, data transformation, content creation
Pattern 3: Specialist Pool
Coordinator routes to the right specialist based on request:
+--------------+
| Coordinator |
+------+-------+
|
+----------------+----------------+
| | |
+---+---+ +----+----+ +----+----+
|Finance| |Technical| | Legal |
+-------+ +---------+ +---------+
Use for: Support routing, expert consultation, domain-specific tasks
Troubleshooting
Agent Not Responding
# Check agent health
agent-hub health coordinator
# Check agent logs
agent-hub logs coordinator --tail 50
# Restart agent
agent-hub restart coordinator
Messages Not Delivered
# Check NATS connection
agent-hub nats status
# View message queue
agent-hub nats queue list
# Replay failed messages
agent-hub nats replay --from "2026-03-10T10:00:00Z"
Agent Errors
# Get detailed error info
agent-hub errors coordinator --last 10
# Common issues:
# - API key expired: Check ANTHROPIC_API_KEY
# - MCP server unavailable: Check mcp_servers config
# - Rate limited: Reduce message frequency
Next Steps
You've built your first agent team. Here's where to go next:
- Add More Agents - Expand your team with specialists
- Connect Data Sources - Give agents access to your systems via MCP
- Build Workflows - Create automated flows for common tasks
- Add Monitoring - Set up dashboards and alerts
- Go to Production - Deploy to Kubernetes for scale
Resources
- Agent.ceo Documentation
- MCP Tool Catalog
- Example Agent Configurations
- Best Practices Guide
- Enterprise Deployment
Conclusion
Building an agent team doesn't have to be complex. Start small:
- One coordinator + one specialist - Prove the concept
- Add tools - Give agents access to useful data
- Add specialists - Expand capabilities as needed
- Add guardrails - Ensure safe, controlled operation
The key insight: agents are most powerful when they collaborate. A well-designed team of specialized agents outperforms a single "do everything" agent.
Ready to build? Get Agent.ceo Lite and have your first agent team running today.
GenBrain.ai runs on Agent.ceo. Our CEO, CTO, and specialist agents collaborate daily to build this platform - demonstrating that agent teams work in production.
Share: