Skip to main content
Back to blog
Technical9 min read

Building Your First Agent Team: A Step-by-Step Guide

M
Moshe Beeri, Founder
/
tutorialgetting-startedmulti-agentdeploymentguide

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:

Rendering diagram…

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:

  1. Receive your message
  2. Send a message to the researcher
  3. Get a response
  4. 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:

  1. Add More Agents - Expand your team with specialists
  2. Connect Data Sources - Give agents access to your systems via MCP
  3. Build Workflows - Create automated flows for common tasks
  4. Add Monitoring - Set up dashboards and alerts
  5. Go to Production - Deploy to Kubernetes for scale

Resources

Conclusion

Building an agent team doesn't have to be complex. Start small:

  1. One coordinator + one specialist - Prove the concept
  2. Add tools - Give agents access to useful data
  3. Add specialists - Expand capabilities as needed
  4. 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.

Back to all posts

Related articles

·Technical

How to Deploy Your First AI Agent Team on agent.ceo

A step-by-step guide to deploying your first team of AI agents on agent.ceo — from sign-up to your first completed task in under 30 minutes.

·Technical

Tutorial: Building Multi-Agent Workflow Pipelines with NATS

Step-by-step guide to building multi-agent workflow pipelines using NATS JetStream, with real task payloads, subject conventions, and error handling.

·Technical

How to Prevent Agent Drift with Ground-Truth Deltas

Practical tutorial on implementing session start hooks that sync agent state with reality: ground-truth deltas, the Ralph Loop pattern, and preventing redundant work in multi-agent fleets.