A2a Server Config

A2A Server Configuration

Provides complete patterns and templates for configuring Agent-to-Agent (A2A) servers with different transport mechanisms (HTTP, STDIO, SSE, WebSocket) following MCP (Model Context Protocol) standards.

Security: API Key Handling

CRITICAL: When generating any configuration files or code:

• NEVER hardcode actual API keys or secrets
• NEVER include real credentials in examples
• NEVER commit sensitive values to git

• ALWAYS use placeholders: your_service_key_here
• ALWAYS create .env.example with placeholders only
• ALWAYS add .env* to .gitignore (except .env.example)
• ALWAYS read from environment variables in code
• ALWAYS document where to obtain keys

Placeholder format: {service}_{env}_your_key_here

Instructions

Phase 1: Analyze Requirements

Determine server configuration needs:

1. Transport Type

• HTTP: Remote access, REST-like communication, CORS support
• STDIO: Local process communication, pipe-based I/O
• SSE (Server-Sent Events): Real-time streaming, one-way server push
• WebSocket: Bidirectional real-time communication

2. Framework Detection

• Python: FastAPI, Flask, Starlette
• TypeScript: Express, Fastify, Node.js native http
• Detect from package.json or requirements.txt

3. Configuration Needs

• Port and host settings
• CORS configuration
• Authentication requirements
• Environment variables

Phase 2: Select and Load Templates

Based on requirements, use templates from templates/:

Python Templates:

• templates/python-http-server.py - FastAPI HTTP server
• templates/python-stdio-server.py - STDIO transport
• templates/python-sse-server.py - SSE streaming
• templates/python-websocket-server.py - WebSocket bidirectional

TypeScript Templates:

• templates/typescript-http-server.ts - Express HTTP server
• templates/typescript-stdio-server.ts - STDIO transport
• templates/typescript-sse-server.ts - SSE streaming
• templates/typescript-websocket-server.ts - WebSocket bidirectional

Phase 3: Configure Transport

Apply configuration based on transport type:

HTTP Configuration:

# Python (FastAPI)
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=True
    )

// TypeScript (Express)
const PORT = process.env.PORT || 8000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

STDIO Configuration:

# Python
mcp.run(transport="stdio")

// TypeScript
server.connect(new StdioServerTransport());

SSE Configuration:

# Python
@app.get("/events")
async def events():
    return EventSourceResponse(event_generator())

WebSocket Configuration:

# Python
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

Phase 4: Add CORS and Security

For HTTP/SSE/WebSocket servers:

# Python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Configure appropriately
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

// TypeScript
import cors from 'cors';
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  credentials: true
}));

Phase 5: Environment Configuration

Create .env.example with placeholders:

# Server Configuration
PORT=8000
HOST=0.0.0.0
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# API Keys (NEVER commit real values)
ANTHROPIC_API_KEY=your_anthropic_key_here
OPENAI_API_KEY=your_openai_key_here

# Transport Settings
TRANSPORT_TYPE=http
ENABLE_CORS=true

Phase 6: Validation

Run validation script:

bash scripts/validate-config.sh <server-file>

Checks:

• No hardcoded API keys
• Environment variable usage
• CORS configuration
• Transport setup validity
• .gitignore includes .env files

Scripts

• scripts/validate-config.sh - Validate server configuration
• scripts/generate-server.sh - Generate server from template
• scripts/test-transport.sh - Test transport connectivity

Templates

Python:

• templates/python-http-server.py - HTTP server with FastAPI
• templates/python-stdio-server.py - STDIO transport
• templates/python-sse-server.py - SSE streaming server
• templates/python-websocket-server.py - WebSocket server

TypeScript:

• templates/typescript-http-server.ts - HTTP server with Express
• templates/typescript-stdio-server.ts - STDIO transport
• templates/typescript-sse-server.ts - SSE streaming server
• templates/typescript-websocket-server.ts - WebSocket server

Examples

• examples/http-fastapi-example.md - Complete HTTP server with FastAPI
• examples/stdio-simple-example.md - Basic STDIO server
• examples/sse-streaming-example.md - SSE streaming configuration
• examples/websocket-bidirectional-example.md - WebSocket bidirectional communication

Requirements

• Framework-specific dependencies (FastAPI/Express/etc.)
• CORS middleware for HTTP/SSE/WebSocket
• Environment variable management (python-dotenv/dotenv)
• No hardcoded API keys or secrets
• .gitignore protection for sensitive files

Use Cases

1. Setting up HTTP server for remote A2A communication

• Load http template
• Configure CORS
• Set environment variables
• Validate configuration

2. Configuring STDIO for local agent communication

• Load stdio template
• Configure process pipes
• Test connectivity

3. Implementing SSE for real-time agent updates

• Load sse template
• Configure event streams
• Set up CORS
• Test streaming

4. Setting up WebSocket for bidirectional agent chat

• Load websocket template
• Configure connection handling
• Set up authentication
• Test bidirectional flow