🏴‍☠️Pirate Agent A2A

Pirate Agent A2A is an autonomous agent designed to simulate conversations with a pirate using the A2A (Agent-to-Agent) protocol. It's built with the A2A server framework and uses Google ADK with LiteLLM for AI interactions.

Project Structure

pirate-agent-a2a/
├── pirate_agent_a2a/
│   ├── __init__.py
│   ├── main.py          # Entry point, runs A2A server
│   └── agent.py         # Pirate agent definition using Google ADK
├── agent.yaml           # A2A server configuration
├── run.sh              # Launch script
├── pyproject.toml      # Python project configuration
├── Dockerfile          # Container configuration
└── README.md           # This file

Key Components

• Main Server: pirate_agent_a2a/main.py - Loads environment and runs A2A server
• Agent Definition: pirate_agent_a2a/agent.py - Defines the pirate agent using Google ADK with enhanced personality
• Configuration: agent.yaml - Server settings, Google ADK handler config, and detailed agent card metadata
• Dependencies: Uses a2a-server>=0.1.0, google-adk>=0.2.0, litellm>=1.67.0, python-dotenv>=1.1.0

Features

• Pirate-speak: Transforms text into authentic pirate lingo
• A2A Protocol: Compatible with A2A agent communication standard
• Streaming: Supports real-time streaming responses
• REST API: Exposes agent via HTTP endpoints

Installation & Setup

1. Clone the repository:

git clone https://github.com/yourusername/pirate-agent-a2a.git
cd pirate-agent-a2a

2. Install dependencies:

uv sync --reinstall

alternatively:

pip install -r requirements.txt

3. Set up environment variables (create .env file):

# Required for LiteLLM - Add your OpenAI API key
OPENAI_API_KEY=your_openai_api_key_here

# Optional: Override default model (currently uses openai/gpt-4o-mini)
# AGENT_MODEL=openai/gpt-4o

# Optional: Server configuration
# PORT=8000
# LOG_LEVEL=debug

Configuration

The agent is configured through multiple files:

• agent.yaml: A2A server configuration, agent cards, and handler settings
• pirate_agent_a2a/agent.py: Agent personality, model selection, and instructions
• .env: Environment variables for API keys and runtime settings

Key Configuration Points

• Model: Currently uses openai/gpt-4o-mini (configurable in agent.py:5)
• Port: Defaults to 8000 (configurable in agent.yaml:3)
• Agent Personality: Defined in instruction field in agent.py:11

Containerization

Build

docker build --load -t pirate-agent:latest .

Deploy to local Podman, Rancher or Docker desktop

docker images ls

1. Get the image id that was pushed
2. Now run the image (on local podman)

podman run --rm -it pirate-agent:latest

Build and deploy to IBM Cloud container registry

In this example, agentic is your icr NAMESPACE and a2a is your REPOSITORY name. Replace RESOURCE_GROUP with the name of the resource group where you want the container registry.

# Log docker into the IBM Clouf container registry at icr.io
ibmcloud cr login 
ibmcloud cr namespace-add -g RESOURCE_GROUP agentic
# Build the image and push it to the container registry in the 'agentic' namespace and 'a2a' repository.
docker build -f Dockerfile --push -t icr.io/agentic/a2a .

Run from source code in IBM Cloud container engine

1. Navigate to Containers/Serverless/Projects

2. Create a project, eg. “A2A-play”

3. Navigate to “Applications”

4. Create application Name: pirate-agent-a2a Code repo URL: https://github.com/ccmitchellusa/pirate-agent-a2a

5. Navigate to "Optional settings" Image start options Listening port: 8000

6. Scroll back up to Code section.

7. Select “Specify build details” > Next > Next >.

8. Select a container registry namespace

9. Select Done

CLI Usage

Start the agent:

./run.sh

The server will start on port 8000. Access endpoints:

• Agent card: http://localhost:8000/agent-card.json
• Health check: http://localhost:8000/health

API Endpoints

Once running, the agent exposes these A2A-compliant endpoints:

Core Endpoints

• GET /agent-card.json - Agent metadata and capabilities
• POST /chat - Send messages to the pirate agent
• POST /chat/stream - Streaming chat responses
• GET /health - Server health status

Example API Usage

# Get agent information
curl http://localhost:8000/agent-card.json

# Send a message to the pirate
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello there!"}'

# Expected response:
# {"response": "Ahoy there, matey! Welcome aboard me ship!"}

A2A Protocol Compatibility

This agent implements the A2A (Agent-to-Agent) protocol, making it compatible with:

• A2A CLI clients
• Other A2A-compliant agents
• A2A orchestration platforms

A2A CLI Usage

To connect with Chris Hay's A2A CLI client (Localhost):

uvx a2a-cli --server http://localhost:8000 chat
# Expected: Interactive chat session with pirate responses
# Example conversation:
# You: Hello!
# Pirate: Ahoy there, matey! Jolly Chris at yer service!

Connect a2a-cli to agent running on Code Engine:

1. In the IBM Cloud console> Code Engine > Application page, click "Test Application" in upper right corner. Copy the app's url.
2. Replace the url in the following snippet with the actual app's url from step 1:

uvx a2a-cli --log-level DEBUG --server https://application-42.1uo9xqkaspg3.us-east.codeengine.appdomain.cloud chat
# DEBUG mode shows detailed request/response information
# Useful for troubleshooting connection issues

Development

Quick Start for Development

# Install dependencies
uv sync --reinstall

# Run locally with debug logging
uv run -m pirate_agent_a2a.main --config agent.yaml --log-level debug

# Alternative: use the run script
./run.sh

Development Workflow

1. Code Structure: Main agent logic in pirate_agent_a2a/agent.py
2. Configuration: Modify agent.yaml for server settings, agent cards
3. Environment: Use .env file for API keys and secrets
4. Dependencies: Managed via pyproject.toml and uv.lock

Testing the Agent

# Test agent card endpoint
curl http://localhost:8000/agent-card.json | jq

# Test basic chat functionality  
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Ahoy!"}'

# Test with A2A CLI
uvx a2a-cli --server http://localhost:8000 chat

Debugging

• Use --log-level debug for verbose output
• Add --list-routes to see all available endpoints
• Use --enable-flow-diagnosis for detailed request tracing
• Check logs for LiteLLM API calls and responses

Common Commands (AI Assistant Reference)

Quick Setup and Run

# Complete setup from scratch
git clone <repo-url> && cd pirate-agent-a2a
echo "OPENAI_API_KEY=your_key_here" > .env
uv sync --reinstall
./run.sh

# Check if running
curl -s http://localhost:8000/health

Development Tasks

# Start with different log levels
uv run -m pirate_agent_a2a.main --config agent.yaml --log-level info
uv run -m pirate_agent_a2a.main --config agent.yaml --log-level debug

# List all available routes
uv run -m pirate_agent_a2a.main --config agent.yaml --list-routes

# Test agent functionality
curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" -d '{"message": "Test message"}'

File Locations for Modifications

• Agent personality/instructions: pirate_agent_a2a/agent.py:19-37
• Model configuration: pirate_agent_a2a/agent.py:17 and environment variable MODEL
• Server port: agent.yaml:4
• Agent metadata: agent.yaml:15-77
• Dependencies: pyproject.toml:7-12
• Handler type: agent.yaml:11 (currently using GoogleADKHandler)

Container Operations

# Build and run with Docker
docker build -t pirate-agent:latest .
docker run --rm -p 8000:8000 pirate-agent:latest

# Quick container test
docker run --rm -p 8000:8000 pirate-agent:latest &
sleep 5 && curl http://localhost:8000/agent-card.json

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Submit a pull request with a detailed description of your changes.

License

This project is licensed under the MIT License.

Acknowledgments

Special thanks to Chris Hayuk and the open-source community for providing tools and inspiration for this project.