KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

agentstack-starter

★ 47 Open GitHub ↗

Starter template to develop agents for Agent Stack

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Agent Stack Starter Template

This repository provides a template for creating a Python agent that can be used with the [Agent Stack](https://agentstack.beeai.dev).

## Overview

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)](https://github.com/a2aproject/A2A) 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

## Project Structure

```sh
├── 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

## Requirements

- [Agent Stack](https://agentstack.beeai.dev/introduction/quickstart) installed
- Python 3.11 or higher
- [UV package manager](https://docs.astral.sh/uv/) for dependency management

## Getting Started

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](src/agentstack_agents/agent.py).

Here's an example of the included template agent:

```py
@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

## Running Agents Locally

To test your agent locally:

```sh
# Start the agent server
uv run server
```

> [!TIP]
> If you want the server to auto-restart on code changes, use this command instead:
> ```sh
> 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:

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

```sh
# List available agents
agentstack list

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

## Adding Agents to Agent Stack

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

### Local Development Mode

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

### Deployment from GitHub

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

#### Version Management

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

## Troubleshooting

### Agent Status

To check the status of your agents:

```sh
# List all agents and their status
agentstack list
```

### Logs

- **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)

agentstack-starter

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README