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:

git clone https://github.com/i-am-bee/beeai-platform-agent-starter my-agent
cd my-agent

Option B – Use as a GitHub template:

  1. Go to the template repository
  2. Click “Use this template” → “Create a new repository”
  3. Clone your new repository locally

​
Install Dependencies

uv sync

​
Test the Template Agent

uv run server  # start the server

Then in another terminal:

beeai run example_agent "Alice"

You should see: “Ciao Alice!” 🎉

Now let’s customize this template.

​
Project Structure

my-agent/
├── src/beeai_agents/
│   ├── __init__.py         # Empty package file
│   └── agent.py            # 👈 Your agent code goes here
├── Dockerfile              # Container configuration
├── pyproject.toml          # Dependencies and metadata
├── uv.lock                 # Dependency lock file
└── README.md               # Project documentation

Important files:

  • agent.py - Where you implement your agent’s behavior
  • pyproject.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:

  1. Example: BeeAI Framework
  2. Example: CrewAI
  3. Example: LangGraph

​
Configure Agent Metadata

The more metadata, the better the UX. Here’s a full example with every supported option:

@server.agent(
    name="my-custom-agent",
    description="A full-featured BeeAI agent with metadata and documentation",
    metadata=Metadata(
        version="1.0.0",
        framework="BeeAI",
        programming_language="Python",
        license="Apache 2.0",
        ui={
            "type": "hands-off",
            "user_greeting": "How can I help you process your data today?"
        },
        author={
            "name": "John Doe",
            "email": "john.doe@example.com",
            "url": "https://johndoe.dev"
        },
        env=[{
            "name": "API_KEY",
            "description": "Required API key for external service integration",
            "required": True
        }],
        recommended_models=[
            "gpt-4o",
            "gpt-4-turbo",
            "claude-3-sonnet"
        ],
        use_cases=[
            "**Data Analysis** – Process structured/unstructured data",
            "**Report Generation** – Produce clean summaries and insights",
            "**Content Summarization** – Shorten long articles or documents"
        ],
        tags=["data-processing", "analysis", "automation", "nlp", "research"],
        documentation="""
### My Custom Agent

This agent provides robust data processing with smart insights powered by AI.

#### Features
- Automatic data type detection
- Multi-format support (CSV, JSON, XML)
- AI-driven summarization and recommendation

#### How It Works
1. Analyze input
2. Process with AI
3. Return structured output

#### Input Formats
- Text
- Structured files
- Environment-specified parameters

#### Output
- JSON with insights, key findings, and confidence scores
"""
    )
)
async def my_custom_agent(...):
    ...

Agent Types:

  • "hands-off": One-shot tasks (summarization, analysis, generation)
  • "chat": Conversational interactions

​
Update Dependencies

Add your agent’s dependencies to pyproject.toml:

dependencies = [
    "acp-sdk>=0.8.1",
    "requests>=2.31.0",     # Add your dependencies here
    "crewai >= 0.30.0"      # For example, CrewAI
]

Then synchronize with uv sync.

​
Test Your Agent

​
Start the Agent Server

uv run 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:

# See all available agents (yours should show up)
beeai list

# Talk to your agent!
beeai run my_agent "Hello!"

If you see a response, congrats - your agent is working!

​
Add Your Agent

Now that your agent works locally, you can at it to the platform by running:

beeai add .

What this does:

  • Builds your agent into a Docker container automatically
  • Adds it directly to your local BeeAI Platform
  • You can immediately use beeai run my_agent "test"