Build New Agents

Start building your own agent with a simple Hello World example

To help you get started quickly, we’ve created a ready-to-use starter repository. You can clone it and start coding right away—no setup headaches or boilerplate required. This guide walks you through running your first “Hello World” agent and then customizing it to make it your own.

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

   git clone https://github.com/i-am-bee/agentstack-starter my-agent
   cd my-agent
   

   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
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 enhance it and learn more:

Agent Details

Customize your agent’s name, description, and how it appears in the UI

Working with Messages

Learn how agents and clients communicate through structured messaging

Multi-Turn Conversations

Understand how to handle multi-turn conversations and maintain context

Working with Files

Work with files to provide inputs or store outputs for your agent