Initial commit

Author: Samir-atra

.github/workflows/test-and-publish.yml

@@ -0,0 +1,88 @@
+name: Test and Publish Agent
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'  # Trigger on version tags like v1.0.0, v1.1.0
+
+jobs:
+  test-and-publish:
+    runs-on: ubuntu-latest
+
+    # These permissions are required for the workflow to:
+    # - Read repository contents (checkout code)
+    # - Write to GitHub Container Registry (push Docker images)
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: false
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          load: true
+          platforms: linux/amd64
+
+      - name: Start agent container
+        env:
+            SECRETS_JSON: ${{ toJson(secrets) }}
+        run: |
+          echo "$SECRETS_JSON" | jq -r 'to_entries[] | "\(.key)=\(.value)"' > .env
+          docker run -d -p 9009:9009 --name agent-container --env-file .env $(echo "${{ steps.meta.outputs.tags }}" | head -n1) --host 0.0.0.0 --port 9009
+          timeout 30 bash -c 'until curl -sf http://localhost:9009/.well-known/agent-card.json > /dev/null; do sleep 1; done'
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install test dependencies
+        run: uv sync --extra test
+
+      - name: Run tests
+        run: uv run pytest -v --agent-url http://localhost:9009
+
+      - name: Stop container and show logs
+        if: always()
+        run: |
+          echo "=== Agent Container Logs ==="
+          docker logs agent-container || true
+          docker stop agent-container || true
+
+      - name: Log in to GitHub Container Registry
+        if: success() && github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Push Docker image
+        if: success() && github.event_name != 'pull_request'
+        run: docker push --all-tags ghcr.io/${GITHUB_REPOSITORY,,}
+
+      - name: Output image digest
+        if: success() && github.event_name != 'pull_request'
+        run: |
+          echo "## Docker Image Published :rocket:" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tags:** ${{ steps.meta.outputs.tags }}" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.env
+.python-version
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

Dockerfile

@@ -0,0 +1,16 @@
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm
+
+RUN adduser agent
+USER agent
+WORKDIR /home/agent
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src src
+
+RUN \
+    --mount=type=cache,target=/home/agent/.cache/uv,uid=1000 \
+    uv sync --locked
+
+ENTRYPOINT ["uv", "run", "src/server.py"]
+CMD ["--host", "0.0.0.0"]
+EXPOSE 9009

README.md

@@ -0,0 +1,87 @@
+# A2A Agent Template
+
+A minimal template for building [A2A (Agent-to-Agent)](https://a2a-protocol.org/latest/) green agents compatible with the [AgentBeats](https://agentbeats.dev) platform.
+
+## Project Structure
+
+```
+src/
+├─ server.py      # Server setup and agent card configuration
+├─ executor.py    # A2A request handling
+├─ agent.py       # Your agent implementation goes here
+└─ messenger.py   # A2A messaging utilities
+tests/
+└─ test_agent.py  # Agent tests
+Dockerfile        # Docker configuration
+pyproject.toml    # Python dependencies
+.github/
+└─ workflows/
+   └─ test-and-publish.yml # CI workflow
+```
+
+## Getting Started
+
+1. **Create your repository** - Click "Use this template" to create your own repository from this template
+
+2. **Implement your agent** - Add your agent logic to [`src/agent.py`](src/agent.py)
+
+3. **Configure your agent card** - Fill in your agent's metadata (name, skills, description) in [`src/server.py`](src/server.py)
+
+4. **Write your tests** - Add custom tests for your agent in [`tests/test_agent.py`](tests/test_agent.py)
+
+For a concrete example of implementing a green agent using this template, see this [draft PR](https://github.com/RDI-Foundation/green-agent-template/pull/3).
+
+## Running Locally
+
+```bash
+# Install dependencies
+uv sync
+
+# Run the server
+uv run src/server.py
+```
+
+## Running with Docker
+
+```bash
+# Build the image
+docker build -t my-agent .
+
+# Run the container
+docker run -p 9009:9009 my-agent
+```
+
+## Testing
+
+Run A2A conformance tests against your agent.
+
+```bash
+# Install test dependencies
+uv sync --extra test
+
+# Start your agent (uv or docker; see above)
+
+# Run tests against your running agent URL
+uv run pytest --agent-url http://localhost:9009
+```
+
+## Publishing
+
+The repository includes a GitHub Actions workflow that automatically builds, tests, and publishes a Docker image of your agent to GitHub Container Registry.
+
+If your agent needs API keys or other secrets, add them in Settings → Secrets and variables → Actions → Repository secrets. They'll be available as environment variables during CI tests.
+
+- **Push to `main`** → publishes `latest` tag:
+```
+ghcr.io/<your-username>/<your-repo-name>:latest
+```
+
+- **Create a git tag** (e.g. `git tag v1.0.0 && git push origin v1.0.0`) → publishes version tags:
+```
+ghcr.io/<your-username>/<your-repo-name>:1.0.0
+ghcr.io/<your-username>/<your-repo-name>:1
+```
+
+Once the workflow completes, find your Docker image in the Packages section (right sidebar of your repository). Configure the package visibility in package settings.
+
+> **Note:** Organization repositories may need package write permissions enabled manually (Settings → Actions → General). Version tags must follow [semantic versioning](https://semver.org/) (e.g., `v1.0.0`).

pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "green-agent-template"
+version = "0.1.0"
+description = "A template for A2A green agents"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "a2a-sdk[http-server]>=0.3.20",
+    "pydantic>=2.12.5",
+    "uvicorn>=0.38.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.28.1",
+]

src/agent.py

@@ -0,0 +1,75 @@
+from typing import Any
+from pydantic import BaseModel, HttpUrl, ValidationError
+from a2a.server.tasks import TaskUpdater
+from a2a.types import Message, TaskState, Part, TextPart, DataPart
+from a2a.utils import get_message_text, new_agent_text_message
+
+from messenger import Messenger
+
+
+class EvalRequest(BaseModel):
+    """Request format sent by the AgentBeats platform to green agents."""
+    participants: dict[str, HttpUrl] # role -> agent URL
+    config: dict[str, Any]
+
+
+class Agent:
+    # Fill in: list of required participant roles, e.g. ["pro_debater", "con_debater"]
+    required_roles: list[str] = []
+    # Fill in: list of required config keys, e.g. ["topic", "num_rounds"]
+    required_config_keys: list[str] = []
+
+    def __init__(self):
+        self.messenger = Messenger()
+        # Initialize other state here
+
+    def validate_request(self, request: EvalRequest) -> tuple[bool, str]:
+        missing_roles = set(self.required_roles) - set(request.participants.keys())
+        if missing_roles:
+            return False, f"Missing roles: {missing_roles}"
+
+        missing_config_keys = set(self.required_config_keys) - set(request.config.keys())
+        if missing_config_keys:
+            return False, f"Missing config keys: {missing_config_keys}"
+
+        # Add additional request validation here
+
+        return True, "ok"
+
+    async def run(self, message: Message, updater: TaskUpdater) -> None:
+        """Implement your agent logic here.
+
+        Args:
+            message: The incoming message
+            updater: Report progress (update_status) and results (add_artifact)
+
+        Use self.messenger.talk_to_agent(message, url) to call other agents.
+        """
+        input_text = get_message_text(message)
+
+        try:
+            request: EvalRequest = EvalRequest.model_validate_json(input_text)
+            ok, msg = self.validate_request(request)
+            if not ok:
+                await updater.reject(new_agent_text_message(msg))
+                return
+        except ValidationError as e:
+            await updater.reject(new_agent_text_message(f"Invalid request: {e}"))
+            return
+
+        # Replace example code below with your agent logic
+        # Use request.participants to get participant agent URLs by role
+        # Use request.config for assessment parameters
+
+        await updater.update_status(
+            TaskState.working, new_agent_text_message("Thinking...")
+        )
+        await updater.add_artifact(
+            parts=[
+                Part(root=TextPart(text="The agent performed well.")),
+                Part(root=DataPart(data={
+                    # structured assessment results
+                }))
+            ],
+            name="Result",
+        )

src/executor.py

@@ -0,0 +1,62 @@
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import (
+    Task,
+    TaskState,
+    UnsupportedOperationError,
+    InvalidRequestError,
+)
+from a2a.utils.errors import ServerError
+from a2a.utils import (
+    new_agent_text_message,
+    new_task,
+)
+
+from agent import Agent
+
+
+TERMINAL_STATES = {
+    TaskState.completed,
+    TaskState.canceled,
+    TaskState.failed,
+    TaskState.rejected
+}
+
+
+class Executor(AgentExecutor):
+    def __init__(self):
+        self.agents: dict[str, Agent] = {} # context_id to agent instance
+
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        msg = context.message
+        if not msg:
+            raise ServerError(error=InvalidRequestError(message="Missing message in request"))
+
+        task = context.current_task
+        if task and task.status.state in TERMINAL_STATES:
+            raise ServerError(error=InvalidRequestError(message=f"Task {task.id} already processed (state: {task.status.state})"))
+
+        if not task:
+            task = new_task(msg)
+            await event_queue.enqueue_event(task)
+
+        context_id = task.context_id
+        agent = self.agents.get(context_id)
+        if not agent:
+            agent = Agent()
+            self.agents[context_id] = agent
+
+        updater = TaskUpdater(event_queue, task.id, context_id)
+
+        await updater.start_work()
+        try:
+            await agent.run(msg, updater)
+            if not updater._terminal_state_reached:
+                await updater.complete()
+        except Exception as e:
+            print(f"Task failed with agent error: {e}")
+            await updater.failed(new_agent_text_message(f"Agent error: {e}", context_id=context_id, task_id=task.id))
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        raise ServerError(error=UnsupportedOperationError())