Skip to main content
Now that your BeeAI Platform is up and running, and you know how to run an agent via the GUI or CLI, it’s time to create your first agent. With the BeeAI SDK, you can build an agent that automatically registers with the platform — no extra setup required. To make things even easier, we’ve provided a starter repository. You can clone it and start coding immediately, so you can focus on your agent logic instead of boilerplate setup.

​
Prerequisites

  • BeeAI Platform installed (Quickstart)
  • uv package manager (should be already installed if you followed the quickstart)

​
Start From Template

1

Use the official starter template

  • Clone directly
  • Use as a GitHub template
git clone https://github.com/i-am-bee/beeai-platform-agent-starter my-agent
cd my-agent
2

Test the Template Agent

uv run server
Enable auto-reload during development: Add watchfiles to automatically restart your server when code changes:
uv run watchfiles beeai_agents.agent.run
3

Run your agent

In another terminal:
beeai run example_agent "Alice"
You should see: “Ciao Alice!” 🎉 With your first agent running, you can now modify it to do anything you want.

​
Implement Your Agent Logic

Navigate to src/beeai_agents/agent.py and replace the example with your agent logic. The starter example is minimal and intended for demonstration purposes only: 
import os

from a2a.types import (
    Message,
)
from a2a.utils.message import get_message_text
from beeai_sdk.server import Server
from beeai_sdk.server.context import Context
from beeai_sdk.a2a.types import AgentMessage

server = Server()

@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 AgentMessage(text=hello_template % get_message_text(input))

def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()
1

Start a server

An agent is essentially an HTTP server. Create a Server instance and run it using run().
2

Mark your agent function

Add the @server.agent decorator to your function so the platform recognizes it as an agent.
3

Name your agent

The function name becomes the agent’s name in the platform.
4

Describe your agent

Write a docstring for the function; it will be extracted and shown as the agent’s description in the platform.
5

Understand the function arguments

  • First argument: an A2A Message.
  • Second argument: a Context object with run details (e.g., task_id, context_id).
6

Extract text from Message

Use get_message_text() to quickly extract the text content from a Message.
7

Make it an async generator

The agent function should be asynchronous and yield results as they’re ready.
8

Send responses easily

  • Yield an AgentMessage (a handy wrapper around A2A Message) for convenience.
  • Or yield a plain str, which will be automatically converted into an A2A Message.

​
Starting from Scratch

If you prefer not to use the starter repo:
  • Create an empty Python project
  • Install beeai-sdk
  • Copy the example code above
The starter repo mainly provides basic scaffolding, a GitHub workflow, and a Dockerfile — all optional.

​
Next Steps

After building your agent, you can:
⌘I