> ## Documentation Index
> Fetch the complete documentation index at: https://agentstack.beeai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. 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](../introduction/quickstart)) and the platform running with `agentstack platform start`
* [uv](https://docs.astral.sh/uv/) package manager (should be already installed if you followed the quickstart)

## 1.  Start From Template

<Steps>
  <Step title="Use the Official Starter Template">
    <Tabs>
      <Tab title="Clone directly">
        ```bash theme={null}
        git clone https://github.com/i-am-bee/agentstack-starter my-agent
        cd my-agent
        ```
      </Tab>

      <Tab title="Use as a GitHub template">
        1. Go to the [template repository](https://github.com/i-am-bee/agentstack-starter)
        2. Click "Use this template" → "Create a new repository"
        3. Clone your new repository locally
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run the Server and Autoregister with Agent Stack">
    ```bash theme={null}
    uv run server
    ```

    <Tip>
      **Enable auto-reload during development:** Add `watchfiles` to automatically restart your server when code changes:

      ```bash theme={null}
      uv run watchfiles agentstack_agents.agent.run
      ```
    </Tip>
  </Step>

  <Step title="Run Your Agent">
    In another terminal:

    ```bash theme={null}
    agentstack run example_agent "Alice"
    ```
  </Step>
</Steps>

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](https://github.com/i-am-bee/agentstack-starter/blob/main/src/agentstack_agents/agent.py) and replace the example with your agent logic.

The starter example is minimal and intended for demonstration purposes only:

```python theme={null}
# 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()

```

<Steps title="Building Your First Agent: Step-by-Step">
  <Step title="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.
  </Step>

  <Step title="Mark Your Agent Function">
    Add the `@server.agent` decorator to your function so the platform recognizes it as an agent.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Understand the Function Arguments">
    * First argument: An [A2A `Message`](https://a2a-protocol.org/latest/specification/#64-message-object). 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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Accordion title="Manual Project Configuration">
  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](#2-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.
</Accordion>

## Next Steps

After building your agent, you can enhance it and learn more:

<CardGroup cols={2}>
  <Card title="Agent Details" icon="id-card" href="/stable/agent-integration/agent-details">
    Customize your agent's name, description, and how it appears in the UI
  </Card>

  <Card title="Working with Messages" icon="comment" href="/stable/agent-integration/messages">
    Learn how agents and clients communicate through structured messaging
  </Card>

  <Card title="Multi-Turn Conversations" icon="comments" href="/stable/agent-integration/multi-turn">
    Understand how to handle multi-turn conversations and maintain context
  </Card>

  <Card title="Working with Files" icon="file" href="/stable/agent-integration/files">
    Work with files to provide inputs or store outputs for your agent
  </Card>
</CardGroup>