Build Your Own Multi-Agent System

Instead of a hello world tutorial, let me show you how to build a live multi-agent system. We'll run it locally on Docker and deploy to production on Railway.

This is a production-grade system that includes:

Feature	Description
Learning	Agents remember and improve over time
Persistence	State, sessions, and memory backed by PostgreSQL
Agentic RAG	Knowledge retrieval that knows when and how to search
MCP Tools	Connect to external services via Model Context Protocol
Monitoring	Full visibility via the AgentOS control plane

You'll also learn how to extend it with your own agents.

5 minute read. Running locally in 5. Deployed to production in 20.

The Agents

We'll build three agents, each demonstrating a different pattern:

Pal - AI-powered second brain. Captures notes, bookmarks, people, meetings. Researches the web. Learns over time.
Knowledge Agent - Answers questions from a knowledge base.
MCP Agent - Connects to external services via MCP.

Each agent can be extended to fit your needs.

Run Locally (5 minutes)

Prerequisites

Install Docker Desktop
Get an OpenAI API key

Setup

Clone the repo and export your OpenAI API key:

git clone \
    https://github.com/agno-agi/agentos-railway-template.git \
    agentos-railway

cd agentos-railway

export OPENAI_API_KEY="sk-***"

Start the application (API + Database):

docker compose up -d --build

That's it. Your system is running. Here's how it looks:

Connect to the UI

Open os.agno.com
Click Add OS → Local
Enter http://localhost:8000 as the URL

Now chat with Pal:

> Note: decided to use Postgres for the new project - better JSON support

> Research event sourcing patterns and save the key findings

> What do I know about event sourcing?

Deploy to Production (10 minutes)

I've made it easy to deploy to Railway - just login and run a script.

Prerequisites

Install the Railway CLI

Deploy

railway login

./scripts/railway_up.sh

The script provisions PostgreSQL, configures environment variables, and deploys your system. Give it a few minutes for the services to spin up.

Connect to the UI

Open os.agno.com
Click Add OS → Live
Enter your Railway domain

You now have a production multi-agent system. Watch it go live in ~2 mins:

What's Included

Pal (Personal Agent that Learns)

Your AI-powered second brain. Captures notes, bookmarks, people, meetings. Researches the web and saves findings. Learns from errors so it doesn't repeat them.

I wrote more about Pal here: Building Pal: Personal Agent that Learns

Knowledge Agent (Agentic RAG)

Store any type of docs in a vector store, chat with it using Agentic RAG.

knowledge_agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    knowledge=knowledge,
    search_knowledge=True,
)

MCP Agent (MCP Tools)

Connects to external tools via the Model Context Protocol. Point it at any MCP server and it gets access to those tools.

mcp_agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[MCPTools(url="https://docs.agno.com/mcp")],
)

Create Your Own Agent

Now let's add a custom agent to the system. We'll build a research agent that uses the Exa MCP server.

Create agents/research_agent.py:

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.mcp import MCPTools

from db import get_postgres_db

# Exa MCP for research
EXA_MCP_URL = (
    f"https://mcp.exa.ai/mcp?tools="
    "web_search_exa,company_research_exa,people_search_exa"
)

research_agent = Agent(
    id="research-agent",
    name="Research Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    db=get_postgres_db(),
    tools=[MCPTools(url=EXA_MCP_URL)],
    instructions="""\
You are a research agent. You help users find information about:
- Companies and startups
- People and their backgrounds
- Topics and trends

Be thorough but concise. Cite your sources.
""",
)

from agents.research_agent import research_agent

agent_os = AgentOS(
    agents=[pal, knowledge_agent, mcp_agent, research_agent],
)

Your agent is now part of the system. Chat with it:

If the agent doesn't show up, press refresh on the UI (top right corner) or restart containers with docker compose restart.

Wrapping Up

You now have a live multi-agent system with:

Feature	Description
Learning	Agents that remember and improve over time
Persistence	PostgreSQL for storing agent sessions, state, and memory
Research	Web search, company lookup, people search via Exa
Monitoring	Full visibility via the AgentOS control plane
Extensibility	Add agents, tools, and integrations as needed

What's Next

Build more agents - Add specialized agents for your use case
Add tools - Extend your agents with 100+ toolkits
Go multi-agent - Create multi-agent teams and workflows
Go multi-channel - Expose your agents via Slack, Discord, WhatsApp
Build an AI product - From 2-person startups to Fortune 500 companies, AgentOS is the foundation for agentic products

The system is yours. You have a head start - make it count.

Learn More

Built with Agno. Give it a ⭐️