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:

from acp_sdk import Metadata
from acp_sdk.models.models import Annotations, CitationMetadata
from acp_sdk.models.platform import PlatformUIAnnotation, PlatformUIType, AgentToolInfo

@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",
        annotations=Annotations(
            beeai_ui=PlatformUIAnnotation(
                ui_type=PlatformUIType.HANDSOFF,
                display_name="My Custom Agent",
                user_greeting="How can I help you process your data today?",
                tools=[AgentToolInfo(name="Wikipedia", description="Search for information on Wikipedia")],
            )
        ),
        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"
        ],
        capabilities=[
            {"name": "Data Analysis", "description": "Process structured/unstructured data"},
            {"name": "Report Generation", "description": "Produce clean summaries and insights"},
            {"name": "Content Summarization", "description": "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(...):
    ...

​
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:

dependencies = [
    "acp-sdk>=0.13.0",
    "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!