Now that your BeeAI Platform is up and running, and you have a basic understanding of how to run the agent via either the GUI or CLI, let’s get to some coding. To build an agent that automatically appears in the platform, all you need to do is use the BeeAI SDK library, which handles the registration process for you. Although building a “Hello World” agent is straightforward, we’ve streamlined the process for you with a starter repository that you can begin editing right away.

​
Prerequisites

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

​
Start From Template

1

Use the official starter template to get started quickly.

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
3

Then in another terminal

beeai run example_agent "Alice"
You should see: “Ciao Alice!” 🎉 With your first agent up and running, you can now modify the code to do whatever you want.

​
Implement Your Agent Logic

Navigate to src/beeai_agents/agent.py and replace the example with your agent implementation. The example implementation doesn’t do much. It’s intended purely for demonstration purposes. 
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

Whatever you name the function will be 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

Want to build your agent without using our starter repo? All you need to do is set up an empty Python project, install beeai-sdk as a dependency, and then use the code above. There’s no magic in the starter repo. It simply provides some basic Python scaffolding, a simple GitHub workflow, and a Dockerfile, most of which are entirely optional.

​
Next Steps

Now that you’ve built your Hello World agent, you can: