Skip to main content
To help you get started quickly, we’ve created a ready-to-use starter repository. The starter repo provides you basic scaffolding, a GitHub workflow, and a Dockerfile. You can clone it and start coding right away—no setup headaches or boilerplate required. Then customize the agent with your own logic.

​
Prerequisites

  • Agent Stack installed (Quickstart) and the platform running with agentstack platform start
  • uv package manager (should be already installed if you followed the quickstart)

​
1. Start From Template

1

Use the Official Starter Template

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

Run the Server and Autoregister with Agent Stack

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.

​
2. Implement Your Agent Logic

In the starter repo, 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: 
# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0

import os

from a2a.types import Message
from a2a.utils.message import get_message_text
from agentstack_sdk.a2a.types import AgentMessage
from agentstack_sdk.server import Server
from agentstack_sdk.server.context import RunContext

server = Server()


@server.agent()
async def implement_your_agent_logic_example(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 and Configure the Server

An agent is essentially an HTTP server. Use server.run() to define how your agent listens for requests:
  • Host: Defaults to 127.0.0.1 (localhost).
  • Port: Defaults to 8000. If you run multiple agents on the same machine, ensure each has a unique port.
2

Mark Your Agent Function

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

Name and Describe Your Agent

  • Identity: The function name (e.g., example_agent) becomes the agent’s unique identifier.
  • Metadata: Write a clear docstring. The SDK extracts this text to serve as the agent’s description in UIs and registries, helping understand what your agent does.
4

Understand the Function Arguments

  • First argument: An A2A Message. Use get_message_text(input) to pull the raw string from the user. This is where you would typically pass data into your LLM or custom processing logic.
  • Second argument: A RunContext object with run details provides metadata about the current execution (e.g., task_id, context_id). Use this if your agent logic needs to track session state or reference specific task parameters.
5

Stream Responses via Async Generator

Agents should be async and use yield. This allows the server to stream responses back to the client in real time. Yield an AgentMessage (a handy wrapper around A2A Message) for convenience or a plain str, which will be automatically converted into an A2A Message.
If you prefer not to use our starter template, you must ensure your project includes these core components to integrate correctly with the Agent Stack platform.
  • The SDK Inegration
    • Add agentstack-sdk to your project dependencies.
    • Your code must initialize a Server() instance from the SDK.
    • You need a designated function that calls server.run(host, port). This is what allows the platform (and Docker) to start your agent.
  • Agent logic remains the same as in the Implement Your Agent Logic section
  • Containerization Requirements
    • If you plan to deploy your agent to the platform (rather than just running it locally), your repository must contain a Dockerfile
  • Git and Platform Metadata
    • The repository must be accessible to the Agent Stack orchestrator if you are using the agentstack add command via URL.
    • Use Git tags (e.g., v1.0.0) if you want to manage stable releases of your agent.

​
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