traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/server/templates/README.md

@@ -0,0 +1,137 @@
+# A2A Utility Agency Templates
+
+This directory contains Jinja2 templates for generating utility agencies that wrap MCP servers and expose them via the A2A (Agent-to-Agent) protocol.
+
+## Overview
+
+These templates follow the pattern established by the [A2A CrewAI examples](https://github.com/google-a2a/a2a-samples/tree/main/samples/python/agents/crewai) to create standardized A2A servers that:
+
+1. **Wrap MCP Servers**: Connect to any MCP (Model Context Protocol) server
+2. **Use CrewAI**: Leverage CrewAI agents to process requests intelligently
+3. **Expose A2A Interface**: Provide a standard A2A protocol interface for agent-to-agent communication
+
+## Templates
+
+### Core Templates
+
+- **`agent.py.j2`** - CrewAI agent implementation that wraps the MCP server
+- **`agent_executor.py.j2`** - A2A executor that interfaces the CrewAI agent with A2A protocol
+- **`__main__.py.j2`** - Main entry point that initializes and starts the A2A server
+
+### Simple Server Template
+
+- **`server.py.j2`** - All-in-one simplified implementation combining agent, executor, and server
+
+### Configuration Templates
+
+- **`agency_config.json.j2`** - Agency configuration file
+- **`pyproject.toml.j2`** - Python project dependencies
+- **`Dockerfile.j2`** - Docker container configuration
+- **`README.md.j2`** - Documentation for the generated agency
+
+## Template Variables
+
+The templates expect the following variables:
+
+### Required Variables
+- `agency_name` - Human-readable name of the agency
+- `agency_id` - Unique identifier for the agency  
+- `mcp_server_name` - Name of the MCP server
+- `mcp_server_url` - URL or path to the MCP server
+- `mcp_server_description` - Description of the MCP server
+- `mcp_server_capabilities` - List of capabilities provided
+
+### Optional Variables
+- `agency_description` - Description of the agency (auto-generated if not provided)
+- `agency_version` - Version of the agency (default: "0.1.0")
+- `mcp_server_type` - Type of MCP server: "stdio", "http", etc. (default: "stdio")
+- `expose_individual_tools` - Whether to expose each MCP tool as a separate A2A skill
+- `auth_required` - Whether authentication is required
+- `auth_schemes` - List of auth schemes if auth is required
+- `skill_examples` - Example prompts for the main skill
+- `additional_dependencies` - Extra Python dependencies
+- `use_simple_server` - Whether to use the simplified server.py template
+
+### Auto-generated Variables
+- `class_name` - PascalCase class name derived from agency_name
+- `package_name` - Python package name (snake_case)
+- `module_name` - Python module name
+- `docker_image` - Docker image name
+
+## Usage
+
+Use the `UtilityAgencyTemplateGenerator` class to generate agencies:
+
+```python
+from traia_iatp.server.template_generator import UtilityAgencyTemplateGenerator
+
+generator = UtilityAgencyTemplateGenerator()
+output_path = generator.generate_agency(
+    output_dir="path/to/output",
+    agency_name="My MCP Agency",
+    agency_id="my-mcp-agency",
+    mcp_server_name="my-mcp-server",
+    mcp_server_url="http://localhost:3000",
+    mcp_server_description="Description of the MCP server",
+    mcp_server_capabilities=["capability1", "capability2"],
+    use_simple_server=True  # For simpler deployments
+)
+```
+
+## Generated Structure
+
+### Simple Server (use_simple_server=True)
+```
+output_dir/
+├── server.py            # All-in-one A2A server
+├── agency_config.json   # Configuration
+├── pyproject.toml       # Dependencies
+├── Dockerfile           # Container config
+├── README.md           # Documentation
+├── docker-compose.yml   # Local development
+├── .gitignore          # Git ignore rules
+└── .env.example        # Environment variables example
+```
+
+### Modular Structure (use_simple_server=False)
+```
+output_dir/
+├── package_name/
+│   ├── __init__.py
+│   ├── agent.py         # CrewAI agent
+│   ├── agent_executor.py # A2A executor
+│   └── __main__.py      # Entry point
+├── agency_config.json
+├── pyproject.toml
+├── Dockerfile
+├── README.md
+├── docker-compose.yml
+├── .gitignore
+└── .env.example
+```
+
+## A2A Protocol Compliance
+
+The generated agencies follow the A2A protocol by:
+
+1. **Agent Card**: Exposing agent capabilities at `/.well-known/agent.json`
+2. **Task Processing**: Handling tasks via POST to `/tasks/send`
+3. **Text I/O**: Supporting text input and output by default
+4. **Request Context**: Processing request context and metadata
+5. **Error Handling**: Proper error responses in A2A format
+
+## Next Steps
+
+After generating an agency:
+
+1. **Test Locally**: Run with `uv run python -m package_name` or `python server.py`
+2. **Build Docker**: `docker build -t agency-name .`
+3. **Push to GitHub**: Use the push_agency_to_repo functionality
+4. **Deploy to Cloud**: Use cloudrun_deployer for Google Cloud Run
+5. **Register**: Add to MongoDB registry for discovery
+
+## References
+
+- [A2A Protocol Documentation](https://github.com/google-a2a/A2A)
+- [A2A CrewAI Examples](https://github.com/google-a2a/a2a-samples/tree/main/samples/python/agents/crewai)
+- [MCP Protocol](https://github.com/anthropics/model-context-protocol) 

traia_iatp/server/templates/README.md.j2

@@ -0,0 +1,425 @@
+# {{ agent_name }}
+
+{{ agent_description }}
+
+## Overview
+
+This utility agent provides access to {{ mcp_server_name }} capabilities through the A2A (Agent-to-Agent) protocol. It acts as a bridge between AI agents and the {{ mcp_server_name }} MCP server.
+
+## Features
+
+- **A2A Protocol Support**: Full implementation of the A2A protocol for agent communication
+- **{{ mcp_server_name }} Integration**: Direct access to {{ mcp_server_name }} tools and capabilities
+- **HTTP/2 Multiplexing**: High-performance concurrent request handling
+- **SSE Streaming**: Real-time streaming responses for compatible operations
+- **Async Operations**: Built with modern async Python for optimal performance
+- **Docker Support**: Easy deployment with Docker and docker-compose
+- **Health Monitoring**: Built-in health check endpoints
+
+## Quick Start
+
+### Using Docker (Recommended)
+
+1. Copy the environment configuration:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Configure your environment variables in `.env` (especially API keys if needed)
+
+3. Run with Docker:
+   ```bash
+   chmod +x run_local_docker.sh
+   ./run_local_docker.sh
+   ```
+
+   Or with docker-compose:
+   ```bash
+   docker-compose up
+   ```
+
+### Manual Setup
+
+1. Install dependencies:
+   ```bash
+   uv sync
+   ```
+
+2. Copy and configure environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+3. Run the server:
+   ```bash
+   uv run python -m {{ agent_id }}
+   ```
+
+## Configuration
+
+All configuration is managed through environment variables. See `.env.example` for available options:
+
+- `PORT`: Server port (default: 8000)
+- `HOST`: Server host (default: 0.0.0.0)
+- `LLM_MODEL`: Language model to use (default: openai/gpt-4.1)
+- `DEBUG_PROTOCOL`: Enable protocol-level debugging (default: false)
+- `USE_TLS`: Enable TLS/HTTPS (default: false)
+- API keys and other service-specific configuration
+
+## API Endpoints
+
+### A2A Protocol Endpoints
+
+The A2A (Agent-to-Agent) protocol defines a minimal set of endpoints for agent communication:
+
+#### 1. **`POST /` (Root Path)** - Main JSON-RPC Endpoint
+This is the primary endpoint for all A2A communication. Despite what you might expect, the A2A library creates the JSON-RPC endpoint at the root path (`/`), not at `/a2a`.
+
+**Supported Methods:**
+- `message/send` - Send a message to the agent
+- `tasks/get` - Get task status
+- `tasks/list` - List tasks
+
+**Example Request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "message/send",
+  "id": "msg-123",
+  "params": {
+    "message": {
+      "messageId": "msg-456",
+      "role": "user",
+      "parts": [{"text": "Get BTC price"}]
+    }
+  }
+}
+```
+
+#### 2. **`GET /.well-known/agent.json`** - Agent Card
+Returns the agent's capabilities, skills, and metadata following the A2A standard.
+
+**Example Response:**
+```json
+{
+  "name": "{{ agent_id }}",
+  "description": "{{ agent_description }}",
+  "version": "{{ agent_version }}",
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": false,
+    "stateTransitionHistory": true
+  },
+  "skills": [...]
+}
+```
+
+#### 3. **`POST /a2a/tasks/subscribe`** - SSE Task Subscription
+Subscribe to real-time updates for a specific task using Server-Sent Events (SSE).
+
+**Request Body:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "tasks/sendSubscribe",
+  "params": {
+    "id": "task-id",
+    "historyLength": 0
+  }
+}
+```
+
+#### 4. **`POST /a2a/tasks/resubscribe`** - SSE Task Resubscription
+Resume a subscription to task events, useful for handling connection drops.
+
+### How Streaming Works
+
+**Important:** Streaming uses the SAME root endpoint (`/`) as regular requests. The difference is in the request parameters:
+
+**Regular Request:**
+```json
+{
+  "params": {
+    "message": {...},
+    "configuration": null  // or omitted
+  }
+}
+```
+
+**Streaming Request:**
+```json
+{
+  "params": {
+    "message": {...},
+    "configuration": {
+      "output_mode": "text/event-stream"  // This enables streaming!
+    },
+    "metadata": {"streaming": true}
+  }
+}
+```
+
+When the server receives `output_mode: "text/event-stream"`, it:
+1. Returns a task ID immediately
+2. Processes the request asynchronously
+3. Streams results via SSE if the client subscribes to `/a2a/tasks/subscribe`
+
+### What About `/health` and `/info`?
+
+These endpoints are **NOT** part of the A2A protocol standard. The A2A protocol is intentionally minimal, focusing only on agent communication. Health monitoring should be implemented at the infrastructure level (e.g., container orchestration health checks).
+
+## A2A Operation Modes
+
+This utility agent supports two primary operation modes through the A2A protocol:
+
+### 1. Synchronous Mode (JSON-RPC)
+
+For simple request-response patterns:
+
+```python
+import httpx
+
+# Direct JSON-RPC request to root endpoint
+request = {
+    "jsonrpc": "2.0",
+    "method": "message/send",
+    "id": "req-123",
+    "params": {
+        "message": {
+            "messageId": "msg-456",
+            "role": "user",
+            "parts": [{"text": "Get BTC price"}]
+        }
+        # Note: no configuration or configuration: null for sync mode
+    }
+}
+
+response = httpx.post("http://localhost:8000/", json=request)
+result = response.json()
+print(result["result"]["parts"][0]["text"])
+```
+
+**How it works:**
+- Client sends a `message/send` request to `/` (root path)
+- No `configuration` parameter or `configuration: null`
+- Server processes the request synchronously
+- Server returns a complete response immediately
+- No task ID, no streaming, no status updates
+
+### 2. Asynchronous Streaming Mode (SSE)
+
+For real-time updates and streaming responses:
+
+```python
+import httpx
+import json
+
+# Step 1: Send streaming request to root endpoint
+request = {
+    "jsonrpc": "2.0",
+    "method": "message/send",
+    "id": "req-123",
+    "params": {
+        "message": {
+            "messageId": "msg-456",
+            "role": "user",
+            "parts": [{"text": "Stream market data for BTC"}]
+        },
+        "configuration": {
+            "output_mode": "text/event-stream"  # This enables streaming!
+        }
+    }
+}
+
+response = httpx.post("http://localhost:8000/", json=request)
+result = response.json()
+task_id = result["result"]["id"]  # Get task ID
+
+# Step 2: Subscribe to SSE events
+subscribe_request = {
+    "jsonrpc": "2.0",
+    "method": "tasks/sendSubscribe",
+    "params": {
+        "id": task_id,
+        "historyLength": 0
+    }
+}
+
+# Use SSE client to receive streaming events
+with httpx.stream("POST", "http://localhost:8000/a2a/tasks/subscribe", 
+                  json=subscribe_request) as sse_response:
+    for line in sse_response.iter_lines():
+        if line.startswith("data: "):
+            event_data = json.loads(line[6:])
+            print(f"Event: {event_data}")
+```
+
+**How it works:**
+- Client sends a `message/send` request to `/` with `output_mode: "text/event-stream"`
+- Server returns a `Task` object with an ID immediately
+- Client subscribes to `/a2a/tasks/subscribe` endpoint for SSE events
+- Server streams events: connection, message chunks, status updates, completion
+
+## MCP Server Details
+
+**Server**: {{ mcp_server_name }}
+**URL**: {{ mcp_server_url }}
+**Type**: {{ mcp_server_type }}
+
+### Available Capabilities
+
+{% for capability in mcp_server_capabilities %}
+- {{ capability }}
+{% endfor %}
+
+## Performance Features
+
+### HTTP/2 Multiplexing
+
+The server supports HTTP/2 for improved performance:
+- Multiple concurrent requests over a single TCP connection
+- Reduced latency and overhead
+- Up to 100 concurrent streams per connection
+
+### Thread Pool Execution
+
+CrewAI operations run in a dedicated thread pool:
+- Prevents blocking the async event loop
+- Enables true concurrent request processing
+- 10 worker threads by default
+
+## Debugging
+
+Enable protocol-level debugging for troubleshooting:
+
+```bash
+DEBUG_PROTOCOL=true ./run_local_docker.sh
+```
+
+This will log:
+- HTTP version and protocol details
+- Request/response timing
+- Connection multiplexing information
+- A2A message flow
+
+## Usage Examples
+
+### Basic Request
+
+```python
+import httpx
+
+# Get agent info
+response = httpx.get("http://localhost:8000/.well-known/agent.json")
+info = response.json()
+
+# Send a message via A2A (note: endpoint is at root "/", not "/a2a")
+request = {
+    "jsonrpc": "2.0",
+    "method": "message/send",
+    "params": {
+        "message": {
+            "messageId": "msg-123",
+            "role": "user",
+            "parts": [{"text": "Get current BTC price"}]
+        }
+    },
+    "id": 1
+}
+
+response = httpx.post("http://localhost:8000/", json=request)  # Root path!
+result = response.json()
+```
+
+### Using A2A Client Library
+
+```python
+from a2a.client import A2AClient, A2ACardResolver
+import httpx
+
+# Create HTTP/2 enabled client
+httpx_client = httpx.AsyncClient(
+    timeout=httpx.Timeout(30.0),
+    transport=httpx.AsyncHTTPTransport(http2=True)
+)
+
+# Discover agent card
+card_resolver = A2ACardResolver(
+    httpx_client=httpx_client,
+    base_url="http://localhost:8000"
+)
+agent_card = await card_resolver.get_agent_card()
+
+# Create A2A client (note: uses base URL, not /a2a)
+client = A2AClient(
+    httpx_client=httpx_client,
+    agent_card=agent_card,
+    url="http://localhost:8000"  # Root URL, not /a2a!
+)
+
+# Simple request
+response = await client.send_message("What's the BTC/USDT price?")
+print(response.result)
+
+# Streaming request
+streaming_request = {
+    "message": {"role": "user", "parts": [{"text": "Stream market data"}]},
+    "configuration": {"output_mode": "text/event-stream"}
+}
+async for chunk in client.send_message_streaming(streaming_request):
+    print(chunk)
+```
+
+## Development
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Building Docker Image
+
+```bash
+docker build -t {{ agent_id }} .
+```
+
+## Deployment
+
+This utility agent can be deployed to:
+- Google Cloud Run (recommended for serverless)
+- AWS ECS/Fargate
+- Kubernetes
+- Any container hosting platform
+
+For production deployments, consider:
+- Setting up proper TLS certificates
+- Configuring appropriate resource limits
+- Implementing rate limiting
+- Setting up monitoring and logging
+
+## Troubleshooting
+
+### 503 Service Unavailable
+- Check server logs: `docker logs -f {{ agent_id }}-local`
+- Ensure MCP server is accessible
+- Verify environment variables are set correctly
+
+### Connection Timeouts
+- Default timeout is 60 seconds
+- For long-running operations, use streaming mode
+- Check if CrewAI operations are completing
+
+### HTTP/2 Not Working
+- HTTP/2 requires TLS in most client libraries
+- Use `USE_TLS=true` for HTTPS support
+- Check client HTTP/2 configuration
+
+## License
+
+[Your License Here]
+
+## Support
+
+For issues and questions, please contact [your-support-email] 

traia_iatp/server/templates/__init__.py

@@ -0,0 +1 @@
+# Template files for generating A2A utility agencies