Build Agents
Bring agents from any framework into BeeAI
This guide shows you how to wrap existing agents from any framework to work with the BeeAI Platform. You’ll learn to use the ACP SDK to create a standardized interface for your agent.
If you’re building new agents from scratch, check out the BeeAI Framework with its native platform integration.
Prerequisites
- BeeAI Platform installed
- Python 3.11 or higher
- UV package manager
- Your existing agent code ready to integrate
Quickstart
Set Up Your Project
Use the official starter template to get started quickly.
Option A – Clone directly:
Option B – Use as a GitHub template:
- Go to the template repository
- Click “Use this template” → “Create a new repository”
- Clone your new repository locally
Install Dependencies
Test the Template Agent
Then in another terminal:
You should see: “Ciao Alice!” 🎉
Now let’s customize this template.
Project Structure
Important files:
agent.py
- Where you implement your agent’s behaviorpyproject.toml
- Add new Python dependencies here
Build Your Custom Agent
Implement Your Agent Logic
Navigate to src/beeai_agents/agent.py and replace the example with your agent implementation.
Tips for Wrapping Agents:
- The function name becomes the agent ID (override with
name=
) - The docstring becomes the description
- Use
input[-1]
to get the latest user message - Send output with
yield MessagePart(content="...")
- Multiple agents? Just add more decorated functions.
Each @server.agent
function defines a new agent service.
Here are examples of wrapping popular agent frameworks:
Configure Agent Metadata
The more metadata, the better the UX. Here’s a full example with every supported option:
Configure UI Annotations in Metadata
UI annotations allow you to customize how your agent appears and behaves in the BeeAI platform. These annotations are part of the ACP (Agent Communication Protocol) metadata and provide rich information about your agent’s capabilities and user experience.
The beeai_ui
annotation is defined within the PlatformUIAnnotation
model and contains properties that control:
- UI Type: How the agent interface behaves (chat vs hands-off)
- User Greeting: Greeting messages and display names
- Tool Information: List of tools that agent is using
Available UI Types:
"hands-off"
: One-shot tasks (summarization, analysis, generation)"chat"
: Conversational interactions
Update Dependencies
Add your agent’s dependencies to pyproject.toml
:
Then synchronize with uv sync
.
Test Your Agent
Start the Agent Server
This launches your agent locally. Keep this terminal open - your agent runs only while this command is active.
Try it with BeeAI
Open a second terminal and run these commands:
If you see a response, congrats - your agent is working!