This repository provides a template for creating a Python agent that can be used with the Agent Stack.

Agent Stack agents are Python-based services that can be run locally or deployed to Agent Stack. Each agent exposes specific functionality through the A2A (Agent2Agent Protocol) which is implemented via SDK.

In this template, you'll find:

• A basic agent implementation
• Docker configuration to ease the build of agent
• Project structure for building your own agents

├── src/                                    # Source code directory
│   └── agentstack_agents/                  # Python package directory
│       ├── __init__.py                     # Package initialization (empty)
│       └── agent.py                        # Agent implementations (main file you'll modify)
├── Dockerfile                              # Container configuration to build the agent
├── pyproject.toml                          # Package metadata and dependencies
├── uv.lock                                 # Dependency lock file (generated by UV)
└── README.md                               # Project documentation

Key files to focus on:

• agent.py: This is where you'll implement your agent logic
• pyproject.toml: Update this if you need to add dependencies
• Dockerfile: Modify if you need special build configuration

• Agent Stack installed
• Python 3.11 or higher
• UV package manager for dependency management

1. Set up your project. Start by using this template for your own agent. You may use this as a template or fork this repository.

2. Install dependencies using uv sync.

3. Implement your agent by modifying the source code located in src/agentstack_agents/agent.py.

Here's an example of the included template agent:

@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 hello_template % get_message_text(input)

Modify this file to implement your own agent's logic. Here are some key points to consider when creating your agent:

• The function name (example_agent above) is used as the unique id for the agent in the platform. You can override this in the details.
• The docstring is used as the agent's description in the platform UI. You can also override this in the details.
• The @server.agent() decorator registers your function as an agent and can customize its appearance and behavior
• get_message_text is exposed from a2a.utils.message to simplify text message extraction
• Your agent receives A2A message in the input
• Return responses using yield AgentMessage or simply yield "some string"
• Access conversation context through the context parameter

To test your agent locally:

# Start the agent server
uv run server

 uv run watchfiles agentstack_agents.agent.run

This will start a local http server on http://127.0.0.1:8000 by default. You'll get an output similar to:

INFO     | uvicorn.error  | Started server process [83016]
INFO     | uvicorn.error  | Waiting for application startup.
INFO     | agentstack_sdk | Registering agent to Agent Stack
INFO     | uvicorn.error  | Application startup complete.
INFO     | uvicorn.error  | Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO     | agentstack_sdk | Agent registered successfully

Your agents should now be started on http://127.0.0.1:8000. You can verify your agents are running with Agent Stack CLI:

# List available agents
agentstack list

# Run the example agent
agentstack run example_agent "Your Name"

There are two ways to add your agent to Agent Stack:

When running agents locally with uv run server, they are automatically registered with Agent Stack. In this mode:

• Agent Stack will communicate with your local server
• You manage the agent's lifecycle (starting/stopping)
• Changes are immediately available without redeployment

To share your agent with others or deploy it to Agent Stack:

• Push your agent code to a GitHub repository
• Add the agent to Agent Stack using: agentstack add https://github.com/your-username/your-repo-name

Agent Stack will automatically:

• Clone your repository
• Build a Docker image
• Start the agent container
• Extract agent configuration directly from the /agents endpoint
• Register the agent in the platform

• For stable versions, use Git tags (e.g., agents-v0.0.1)
• When adding a tagged version: agentstack add https://github.com/your-username/[email protected]
• To update: remove the old version (agentstack remove <agent-name>) and add the new one

To check the status of your agents:

# List all agents and their status
agentstack list

• Local agents: View logs directly in the terminal where you ran uv run server
• Managed agents: Use agentstack logs <agent-id> to view logs
• Agent Stack server logs: Check /opt/homebrew/var/log/agentstack-server.log (default location)