Kagenti ADK Starter Template

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

Overview

Kagenti ADK agents are Python-based services that can be run locally or deployed to Kagenti ADK. 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

Project Structure

├── src/                                    # Source code directory
│   └── kagenti_adk_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

• Kagenti ADK installed
• Python 3.11 or higher
• UV package manager 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/kagenti_adk_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

Running Agents Locally

To test your agent locally:

# Start the agent server
uv run server

Tip

If you want the server to auto-restart on code changes, use this command instead:

uv run watchfiles kagenti_adk_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     | kagenti_adk    | Registering agent to Kagenti ADK
INFO     | uvicorn.error  | Application startup complete.
INFO     | uvicorn.error  | Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO     | kagenti_adk    | Agent registered successfully

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

# List available agents
kagenti-adk list

# Run the example agent
kagenti-adk run example_agent "Your Name"

Adding Agents to Kagenti ADK

There are two ways to add your agent to Kagenti ADK:

Local Development Mode

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

• Kagenti ADK 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 Kagenti ADK:

• Push your agent code to a GitHub repository
• Add the agent to Kagenti ADK using: kagenti-adk add https://github.com/your-username/your-repo-name

Kagenti ADK 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: kagenti-adk add https://github.com/your-username/[email protected]
• To update: remove the old version (kagenti-adk remove <agent-name>) and add the new one

Troubleshooting

Agent Status

To check the status of your agents:

# List all agents and their status
kagenti-adk list

Logs

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