BeeAI Platform Agent Template

This repository provides a template for creating a Python agent that can be used with the BeeAI Platform.

Overview

BeeAI agents are Python-based services that can be run locally or deployed to the BeeAI Platform. Each agent exposes specific functionality through the A2A (Agent2Agent Protocol) which is implemented via SDK.

In this template, you'll find:

• A basic agent implementation
• Docker configuration to ease the build of agent
• Project structure for building your own agents

Project Structure

├── src/                                    # Source code directory
│   └── beeai_agents/                       # Python package directory
│       ├── __init__.py                     # Package initialization (empty)
│       └── agent.py                        # Agent implementations (main file you'll modify)
├── Dockerfile                              # Container configuration to build the agent
├── pyproject.toml                          # Package metadata and dependencies
├── uv.lock                                 # Dependency lock file (generated by UV)
└── README.md                               # Project documentation

Key files to focus on:

• agent.py: This is where you'll implement your agent logic
• pyproject.toml: Update this if you need to add dependencies
• Dockerfile: Modify if you need special build configuration

Requirements

• BeeAI Platform installed
• Python 3.11 or higher
• UV package manager for dependency management

Getting Started

1. Set up your project. Start by using this template for your own agent. You may use this as a template or fork this repository.

2. Install dependencies using uv sync.

3. Implement your agent by modifying the source code located in src/beeai_agents/server.py.

Here's an example of the included template agent:

@server.agent()
async def example_agent(input: Message, context: Context):
    """Polite agent that greets the user"""
    hello_template: str = os.getenv("HELLO_TEMPLATE", "Ciao %s!")
    yield hello_template % get_message_text(input)

Modify this file to implement your own agent's logic. Here are some key points to consider when creating your agent:

• The function name (example_agent above) is used as the unique id for the agent in the platform. You can override this in the details.
• The docstring is used as the agent's description in the platform UI. You can also override this in the details.
• The @server.agent() decorator registers your function as an agent and can customize its appearance and behavior
• get_message_text is exposed from a2a.utils.message to simplify text message extraction
• Your agent receives A2A message in the input
• Return responses using yield AgentMessage or simply yield "some string"
• Access conversation context through the context parameter

Running Agents Locally

To test your agent locally:

# Start the agent server
uv run server

This will start a local http server on http://127.0.0.1:8000 by default. You'll get an output similar to:

INFO     | uvicorn.error | Started server process [83016]
INFO     | uvicorn.error | Waiting for application startup.
INFO     | beeai_sdk    | Registering agent to the beeai platform
INFO     | uvicorn.error | Application startup complete.
INFO     | uvicorn.error | Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO     | beeai_sdk    | Agent registered successfully

Your agents should now be started on http://127.0.0.1:8000. You can verify your agents are running with the BeeAI CLI:

# List available agents
beeai list

# Run the example agent
beeai run example_agent "Your Name"

Adding Agents to BeeAI Platform

There are two ways to add your agent to the BeeAI Platform:

Local Development Mode

When running agents locally with uv run server, they are automatically registered with the BeeAI Platform. In this mode:

• The BeeAI Platform will communicate with your local server
• You manage the agent's lifecycle (starting/stopping)
• Changes are immediately available without redeployment

Deployment from GitHub

To share your agent with others or deploy it to the BeeAI Platform:

• Push your agent code to a GitHub repository
• Add the agent to BeeAI using: beeai add https://github.com/your-username/your-repo-name

The BeeAI Platform will automatically:

• Clone your repository
• Build a Docker image
• Start the agent container
• Extract agent configuration directly from the /agents endpoint
• Register the agent in the platform

Version Management

• For stable versions, use Git tags (e.g., agents-v0.0.1)
• When adding a tagged version: beeai add https://github.com/your-username/[email protected]
• To update: remove the old version (beeai remove <agent-name>) and add the new one

Troubleshooting

Agent Status

To check the status of your agents:

# List all agents and their status
beeai list

Logs

• Local agents: View logs directly in the terminal where you ran uv run server
• Managed agents: Use beeai logs <agent-id> to view logs
• BeeAI server logs: Check /opt/homebrew/var/log/beeai-server.log (default location)