Skip to main content
Now that your Agent Stack 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 Agent Stack SDK, you can build an agent that automatically registers with the Agent Stack — 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

  • Agent Stack 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/agentstack-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 agentstack_agents.agent.run
3

Run your agent

In another terminal:
agentstack 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/agentstack_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 agentstack_sdk.server import Server
from agentstack_sdk.server.context import RunContext
from agentstack_sdk.a2a.types import AgentMessage

server = Server()

@server.agent()
async def example_agent(input: Message, context: RunContext):
    """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 RunContext 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 agentstack-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: