PRs: welcome

" } ], "index": 0, "append": true, "lastChunk": false } ] } } ``` ### Non-textual Media Following is an example interaction between a client and an agent with non-textual data. #### Request - seq 1 ```json { "jsonrpc": "2.0", "id": 9, "method": "tasks/send", "params": { "id": "de38c76d-d54c-436c-8b9f-4c2703648d64", "sessionId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "message": { "role": "user", "parts": [ { "type": "text", "text": "Analyze the attached report and generate high level overview" }, { "type": "file", "file": { "mimeType": "application/pdf", "data": "" } } ] }, "metadata": {} } } ``` #### Response - seq 2 ```json { "jsonrpc": "2.0", "id": 9, "result": { "id": "de38c76d-d54c-436c-8b9f-4c2703648d64", "sessionId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "working", "message": { "role": "agent", "parts": [ { "type": "text", "text": "analysis in progress, please wait" } ], "metadata": {} } }, "metadata": {} } } ``` #### Request - seq 3 ```json { "jsonrpc": "2.0", "id": 10, "method": "tasks/get", "params": { "id": "de38c76d-d54c-436c-8b9f-4c2703648d64", "metadata": {} } } ``` #### Response - seq 4 ```json { "jsonrpc": "2.0", "id": 9, "result": { "id": "de38c76d-d54c-436c-8b9f-4c2703648d64", "sessionId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "completed" }, "artifacts": [ { "parts": [ { "type": "text", "text": "" } ], "metadata": {} } ], "metadata": {} } } ``` ### Structured Output Both the client or the agent can request structured output from the other party. #### Request ```json { "jsonrpc": "2.0", "id": 9, "method": "tasks/send", "params": { "id": "de38c76d-d54c-436c-8b9f-4c2703648d64", "sessionId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "message": { "role": "user", "parts": [ { "type": "text", "text": "Show me a list of my open IT tickets", "metadata": { "mimeType": "application/json", "schema": { "type": "array", "items": { "type": "object", "properties": { "ticketNumber": { "type": "string" }, "description": { "type": "string" } } } } } } ] }, "metadata": {} } } ``` #### Response ```json { "jsonrpc": "2.0", "id": 9, "result": { "id": "de38c76d-d54c-436c-8b9f-4c2703648d64", "sessionId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "working", "message": { "role": "agent", "parts": [ { "type": "text", "text": "[{\"ticketNumber\":\"REQ12312\",\"description\":\"request for VPN access\"},{\"ticketNumber\":\"REQ23422\",\"description\":\"Add to DL - team-gcp-onboarding\"}]" } ], "metadata": {} } }, "metadata": {} } } ``` ## /docs/a2a-typescript-guide.md # A2A Protocol Development Guide （TypeScript） ## Overview The A2A (Agent-to-Agent) protocol is a JSON-RPC based communication protocol designed for agent interactions. This guide provides comprehensive instructions for developing both server and client components that conform to the A2A protocol specification. ## Table of Contents 1. [Protocol Basics](#protocol-basics) 2. [Server Implementation](#server-implementation) 3. [Client Implementation](#client-implementation) 4. [Running the Coder Demo](#running-the-coder-demo) ## Protocol Basics The A2A protocol is built on top of JSON-RPC 2.0 and defines a set of methods for agent communication. Key components include: ### Message Structure All A2A messages follow the JSON-RPC 2.0 format with the following base structure: ```typescript interface JSONRPCMessage { jsonrpc?: "2.0"; id?: number | string | null; method?: string; params?: unknown; result?: unknown; error?: JSONRPCError; } ``` ### Protocol Flow The following sequence diagram illustrates the main interaction flow of the A2A protocol: ![a2a typical flow](/images/a2a-guide-typescript.png) ### Core Methods The protocol supports several core methods: - `tasks/send`: Send a task message to an agent - `tasks/get`: Retrieve task status - `tasks/cancel`: Cancel a running task - `tasks/pushNotification/set`: Configure push notifications for a task - `tasks/pushNotification/get`: Get push notification configuration - `tasks/resubscribe`: Resubscribe to task updates - `tasks/sendSubscribe`: Send a task message and subscribe to updates ### Task States Tasks can be in one of the following states: - `submitted` - `working` - `input-required` - `completed` - `canceled` - `failed` - `unknown` ## Server Implementation ### Core Components The server implementation consists of several key components: 1. **Server (server.ts)**: Main server implementation handling HTTP requests 2. **Handler (handler.ts)**: Request handler for processing A2A protocol messages 3. **Store (store.ts)**: Task storage and management 4. **Utils (utils.ts)**: Utility functions 5. **Error Handling (error.ts)**: Error definitions and handling ### Basic Usage (Conceptual) ```typescript import { A2AServer, InMemoryTaskStore, TaskContext, TaskYieldUpdate, } from "./index"; // Assuming imports from the server package // 1. Define your agent's logic as a TaskHandler async function* myAgentLogic( context: TaskContext ): AsyncGenerator { console.log(`Handling task: ${context.task.id}`); yield { state: "working", message: { role: "agent", parts: [{ text: "Processing..." }] }, }; // Simulate work... await new Promise((resolve) => setTimeout(resolve, 1000)); if (context.isCancelled()) { console.log("Task cancelled!"); yield { state: "canceled" }; return; } // Yield an artifact yield { name: "result.txt", mimeType: "text/plain", parts: [{ text: `Task ${context.task.id} completed.` }], }; // Yield final status yield { state: "completed", message: { role: "agent", parts: [{ text: "Done!" }] }, }; } // 2. Create and start the server const store = new InMemoryTaskStore(); // Or new FileStore() const server = new A2AServer(myAgentLogic, { taskStore: store }); server.start(); // Starts listening on default port 41241 console.log("A2A Server started."); ``` ## Client Implementation ### Key Features: - **JSON-RPC Communication:** Handles sending requests and receiving responses (both standard and streaming via Server-Sent Events) according to the JSON-RPC 2.0 specification. - **A2A Methods:** Implements standard A2A methods like `sendTask`, `sendTaskSubscribe`, `getTask`, `cancelTask`, `setTaskPushNotification`, `getTaskPushNotification`, and `resubscribeTask`. - **Error Handling:** Provides basic error handling for network issues and JSON-RPC errors. - **Streaming Support:** Manages Server-Sent Events (SSE) for real-time task updates (`sendTaskSubscribe`, `resubscribeTask`). - **Extensibility:** Allows providing a custom `fetch` implementation for different environments (e.g., Node.js). ### Basic Usage ```typescript import { A2AClient, Task, TaskQueryParams, TaskSendParams } from "./client"; // Import necessary types import { v4 as uuidv4 } from "uuid"; // Example for generating task IDs const client = new A2AClient("http://localhost:41241"); // Replace with your server URL async function run() { try { // Send a simple task (pass only params) const taskId = uuidv4(); const sendParams: TaskSendParams = { id: taskId, message: { role: "user", parts: [{ text: "Hello, agent!" }] }, }; // Method now returns Task | null directly const taskResult: Task | null = await client.sendTask(sendParams); console.log("Send Task Result:", taskResult); // Get task status (pass only params) const getParams: TaskQueryParams = { id: taskId }; // Method now returns Task | null directly const getTaskResult: Task | null = await client.getTask(getParams); console.log("Get Task Result:", getTaskResult); } catch (error) { console.error("A2A Client Error:", error); } } run(); ``` ### Streaming Usage ```typescript import { A2AClient, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, TaskSendParams, // Use params type directly } from "./client"; // Adjust path if necessary import { v4 as uuidv4 } from "uuid"; const client = new A2AClient("http://localhost:41241"); async function streamTask() { const streamingTaskId = uuidv4(); try { console.log(`\n--- Starting streaming task ${streamingTaskId} ---`); // Construct just the params const streamParams: TaskSendParams = { id: streamingTaskId, message: { role: "user", parts: [{ text: "Stream me some updates!" }] }, }; // Pass only params to the client method const stream = client.sendTaskSubscribe(streamParams); // Stream now yields the event payloads directly for await (const event of stream) { // Type guard to differentiate events based on structure if ("status" in event) { // It's a TaskStatusUpdateEvent const statusEvent = event as TaskStatusUpdateEvent; // Cast for clarity console.log( `[${streamingTaskId}] Status Update: ${statusEvent.status.state} - ${ statusEvent.status.message?.parts[0]?.text ?? "No message" }` ); if (statusEvent.final) { console.log(`[${streamingTaskId}] Stream marked as final.`); break; // Exit loop when server signals completion } } else if ("artifact" in event) { // It's a TaskArtifactUpdateEvent const artifactEvent = event as TaskArtifactUpdateEvent; // Cast for clarity console.log( `[${streamingTaskId}] Artifact Update: ${ artifactEvent.artifact.name ?? `Index ${artifactEvent.artifact.index}` } - Part Count: ${artifactEvent.artifact.parts.length}` ); // Process artifact content (e.g., artifactEvent.artifact.parts[0].text) } else { console.warn("Received unknown event structure:", event); } } console.log(`--- Streaming task ${streamingTaskId} finished ---`); } catch (error) { console.error(`Error during streaming task ${streamingTaskId}:`, error); } } streamTask(); ``` ## Running the Coder Demo The Coder Demo is an example implementation of an A2A agent that can process code-related tasks. ### Setup 1. Install dependencies: ```bash git clone https://github.com/sing1ee/a2a-agent-coder.git #or git clone git@github.com:sing1ee/a2a-agent-coder.git bun install ``` 2. Ensure you have the required environment variables: ```bash # set .env first export $(cat .env | xargs) ``` ### Running the Demo 1. Start the a2a server (requires Node.js environment): ```bash bun run agents:coder ``` 2. Start the a2a client: ```bash bun run a2a:cli # result $ bun x tsx src/cli.ts A2A Terminal Client Agent URL: http://localhost:41241 Attempting to fetch agent card from: http://localhost:41241/.well-known/agent.json ✓ Agent Card Found: Name: Coder Agent Description: An agent that generates code based on natural language instructions and streams file outputs. Version: 0.0.1 Starting Task ID: a1a608b3-3015-4404-a83f-6ccc05083761 Enter messages, or use '/new' to start a new task. Coder Agent > You: implement binary search Sending... Coder Agent [4:28:00 PM]: ⏳ Status: working Part 1: 📝 Text: Generating code... Coder Agent [4:28:02 PM]: ⏳ Status: working Part 1: 📄 File: Name: src/algorithms/binary_search.py, Source: """ Implementation of the binary search algorithm in Python. """ def binary_search(arr, target): """ Performs a binary search on a sorted array to find the index of a target value. Args: arr (list): A sorted list of elements. target: The value to search for in the array. Returns: int: The index of the target value if found, otherwise -1. """ low = 0 high = len(arr) - 1 while low <= high: mid = (low + high) // 2 # Integer division to find the middle index if arr[mid] == target: return mid # Target found at index mid elif arr[mid] < target: low = mid + 1 # Target is in the right half else: high = mid - 1 # Target is in the left half return -1 # Target not found in the array Coder Agent [4:28:02 PM]: ✅ Status: completed SSE stream finished for method tasks/sendSubscribe. --- End of response for this input --- Coder Agent > You: Exiting terminal client. Goodbye! ``` ## Error Handling The A2A protocol defines several standard error codes: - `-32700`: Parse error - `-32600`: Invalid request - `-32601`: Method not found - `-32602`: Invalid params - `-32603`: Internal error - `-32000`: Task not found - `-32001`: Task not cancelable - `-32002`: Push notification not supported - `-32003`: Unsupported operation ## Best Practices 1. **Error Handling**: Always implement proper error handling for all A2A protocol methods 2. **Authentication**: Implement proper authentication mechanisms for secure communication 3. **Task Management**: Maintain proper task state management and cleanup 4. **Push Notifications**: Implement push notifications for real-time updates when supported 5. **Logging**: Implement comprehensive logging for debugging and monitoring ## Additional Resources - [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) - [A2A Protocol Schema](https://github.com/sing1ee/a2a-agent-coder/tree/main/src/schema.ts) - [Server Implementation](https://github.com/sing1ee/a2a-agent-coder/tree/main/src/server) - [Client Implementation](https://github.com/sing1ee/a2a-agent-coder/tree/main/src/client) - [Coder Agent Implementation](https://github.com/sing1ee/a2a-agent-coder/tree/main/src/agents/coder) ## /docs/a2a-vs-mcp.md # A2A vs MCP: The Protocol Revolution in AI Architecture In today's rapidly evolving AI landscape, two key protocols are reshaping how we build intelligent systems: Google's Agent-to-Agent Protocol (A2A) and the Model Context Protocol (MCP). These protocols represent different dimensions of AI architecture development, but together they point toward a future where we're moving from deterministic programming to autonomous collaborative systems. ## The Fundamental Distinction: Tools vs Agents **MCP** (Model Context Protocol) is essentially a protocol for **tool access**. It defines a standard way for large language models to interact with various tools, data, and resources. Simply put, MCP enables AI to use various functionalities, much like how programmers call functions. **A2A** (Agent-to-Agent Protocol) focuses on **agent collaboration**. It establishes ways for intelligent agents to discover, communicate, and cooperate with each other, allowing different AI systems to work together like human teams. ## An Illustrative Metaphor: Workshop vs Conference Room Think of the difference between these protocols as: - **MCP is a tool workshop**: It lets workers (AI models) know the location, purpose, and usage of each tool (API, function), but doesn't guide how workers collaborate. - **A2A is a conference room**: It allows different professionals (specialized AI agents) to sit together, understand each other's expertise, and coordinate how to jointly complete complex tasks. ## The Auto Repair Shop Example Imagine an autonomous auto repair shop with multiple AI mechanics: - **MCP's role**: Enables mechanics to know how to use specific tools like jacks, wrenches, and testing devices. Structured instructions like "raise platform by 2 meters" or "turn wrench 4mm to the right." - **A2A's role**: Allows customers to communicate with mechanics ("my car is making a rattling noise") and enables mechanics to collaborate with each other or with parts supplier agents. "Send me a picture of the left wheel," "I notice fluid leaking. How long has that been happening?" ## Technical Comparison |Aspect|MCP|A2A| |---|---|---| |**Core Focus**|Model-to-tool connection|Agent-to-agent collaboration| |**Interaction Mode**|Function calls, structured I/O|Conversational, long-running tasks| |**Application Scenarios**|Tool integration, API calls, resource access|Multi-agent collaboration, complex task decomposition, service discovery| |**Abstraction Level**|Low-level (specific functionalities)|High-level (intent and capabilities)| |**Standardization Status**|Gradually standardizing|In early development stage| ## Advantages and Challenges ### MCP Advantages - Clear structure, predictable execution - Simple integration with existing API frameworks - Reduces complexity in connecting AI with tools - Relatively low performance overhead ### MCP Challenges - Limited flexibility, requires explicit definition of each tool - Not ideal for highly dynamic or unknown tasks - Difficulty expressing complex collaborative requirements ### A2A Advantages - Supports dynamic discovery and impromptu collaboration - Suitable for open-ended, complex tasks - Closer to natural human team collaboration patterns - Highly scalable, easy to add new agents ### A2A Challenges - Complex state consistency management - Security and access control challenges - Significant reasoning overhead - Immature partial failure handling mechanisms ## Complementary Rather Than Competitive A2A and MCP are not competing technologies but complementary ones. In practical applications, they often need to be used together: - MCP provides a standard way for agents to access tools - A2A provides a standard way for agents to collaborate In practice, a complete AI system architecture typically requires: 1. Using MCP to connect AI with various tools and data sources 2. Using A2A to implement collaboration and task delegation between multiple agents ## Future Development Trends ### Likely Short-term Developments - MCP will continue to standardize, becoming a universal tool access protocol across models and frameworks - A2A will begin to be validated in complex business applications - Both protocols will be integrated into mainstream AI development frameworks ### Long-term Outlook - We'll see a shift from deterministic programming to intent-oriented programming - Software systems will increasingly resemble capable intelligent teams rather than fixed processes - A new generation of security standards and best practices will emerge around agent collaboration - The developer role may transform from "instruction writer" to "capability describer" and "collaboration designer" ## Conclusion MCP and A2A represent two key dimensions in building AI systems - one oriented toward tool integration, the other toward agent collaboration. Together, they signal a fundamental shift in the software development paradigm: from explicit programming to descriptive, autonomous, and collaborative systems. As these protocols mature, we can expect increasingly intelligent, flexible, and powerful AI applications - applications that don't just execute predefined instructions but can autonomously think, adapt, and collaborate to accomplish complex tasks. We're no longer just programming software; we're collaborating with intelligent systems. This isn't merely an evolution in AI architecture; it's a revolution in the entire approach to software development. ## /docs/python-a2a.md # Python A2A: A Comprehensive Guide to Google's Agent-to-Agent Protocol ## Introduction Python A2A is an implementation of Google's Agent-to-Agent (A2A) protocol, designed to standardize communication between AI agents. This protocol solves a major challenge in the AI ecosystem: enabling different AI services to communicate seamlessly without custom translation layers. As the AI landscape fragments into specialized services, each with its own API format and parameters, developers spend excessive time building communication infrastructure rather than focusing on AI logic. Python A2A addresses this by providing a standardized way for AI agents to talk to each other, regardless of their underlying implementation. ## Getting Started with Python A2A ### Installation ```bash # Basic installation pip install python-a2a # For OpenAI integration pip install "python-a2a[openai]" # For Anthropic Claude integration pip install "python-a2a[anthropic]" # For all optional dependencies pip install "python-a2a[all]" ``` ## Core Concepts Python A2A implements several key concepts from the A2A protocol: 1. **Message Structure**: Defined formats for text, function calls, and responses 2. **Conversation Threading**: Support for maintaining context across interactions 3. **Function Calling**: Standardized way for agents to expose and call functions 4. **Error Handling**: Consistent error formats ## Building Your First A2A Agent Let's start with a simple echo agent that responds to messages: ```python from python_a2a import A2AServer, Message, TextContent, MessageRole, run_server class EchoAgent(A2AServer): """A simple agent that echoes back messages with a prefix.""" def handle_message(self, message): if message.content.type == "text": return Message( content=TextContent(text=f"Echo: {message.content.text}"), role=MessageRole.AGENT, parent_message_id=message.message_id, conversation_id=message.conversation_id ) # Run the server if __name__ == "__main__": agent = EchoAgent() run_server(agent, host="0.0.0.0", port=5000) ``` Now, let's create a client to talk to our agent: ```python from python_a2a import A2AClient, Message, TextContent, MessageRole # Create a client to talk to our agent client = A2AClient("http://localhost:5000/a2a") # Send a message message = Message( content=TextContent(text="Hello, is this thing on?"), role=MessageRole.USER ) response = client.send_message(message) # Print the response print(f"Agent says: {response.content.text}") ``` ## Function Calling Between Agents One of the powerful features of A2A is standardized function calling. Here's a calculator agent that exposes mathematical functions: ```python import math from python_a2a import ( A2AServer, Message, TextContent, FunctionCallContent, FunctionResponseContent, FunctionParameter, MessageRole, run_server ) class CalculatorAgent(A2AServer): """An agent that provides mathematical calculation functions.""" def handle_message(self, message): if message.content.type == "text": return Message( content=TextContent( text="I'm a calculator agent. You can call my functions:\n" "- calculate: Basic arithmetic (operation, a, b)\n" "- sqrt: Square root (value)" ), role=MessageRole.AGENT, parent_message_id=message.message_id, conversation_id=message.conversation_id ) elif message.content.type == "function_call": function_name = message.content.name params = {p.name: p.value for p in message.content.parameters} try: if function_name == "calculate": operation = params.get("operation", "add") a = float(params.get("a", 0)) b = float(params.get("b", 0)) if operation == "add": result = a + b elif operation == "subtract": result = a - b elif operation == "multiply": result = a * b elif operation == "divide": if b == 0: raise ValueError("Cannot divide by zero") result = a / b else: raise ValueError(f"Unknown operation: {operation}") return Message( content=FunctionResponseContent( name="calculate", response={"result": result} ), role=MessageRole.AGENT, parent_message_id=message.message_id, conversation_id=message.conversation_id ) elif function_name == "sqrt": value = float(params.get("value", 0)) if value < 0: raise ValueError("Cannot calculate square root of negative number") result = math.sqrt(value) return Message( content=FunctionResponseContent( name="sqrt", response={"result": result} ), role=MessageRole.AGENT, parent_message_id=message.message_id, conversation_id=message.conversation_id ) except Exception as e: return Message( content=FunctionResponseContent( name=function_name, response={"error": str(e)} ), role=MessageRole.AGENT, parent_message_id=message.message_id, conversation_id=message.conversation_id ) if __name__ == "__main__": agent = CalculatorAgent() run_server(agent, host="0.0.0.0", port=5001) ``` Here's how to call the calculator agent's functions: ```python from python_a2a import ( A2AClient, Message, FunctionCallContent, FunctionParameter, MessageRole ) client = A2AClient("http://localhost:5001/a2a") # Create a function call message function_call = Message( content=FunctionCallContent( name="calculate", parameters=[ FunctionParameter(name="operation", value="add"), FunctionParameter(name="a", value=5), FunctionParameter(name="b", value=3) ] ), role=MessageRole.USER ) response = client.send_message(function_call) if response.content.type == "function_response": result = response.content.response.get("result") if result is not None: print(f"Result: {result}") # Output: Result: 8 ``` ## LLM-Powered Agents Python A2A includes ready-to-use integrations with popular LLM providers. Here's an OpenAI-powered agent: ```python import os from python_a2a import OpenAIA2AServer, run_server # Create an agent powered by OpenAI agent = OpenAIA2AServer( api_key=os.environ["OPENAI_API_KEY"], model="gpt-4", system_prompt="You are a helpful AI assistant." ) # Run the server if __name__ == "__main__": run_server(agent, host="0.0.0.0", port=5002) ``` Similarly, you can create an Anthropic Claude-powered agent: ```python import os from python_a2a import ClaudeA2AServer, run_server # Create an agent powered by Anthropic Claude agent = ClaudeA2AServer( api_key=os.environ["ANTHROPIC_API_KEY"], model="claude-3-opus-20240229", system_prompt="You are a helpful AI assistant." ) # Run the server if __name__ == "__main__": run_server(agent, host="0.0.0.0", port=5003) ``` ## Multi-Agent Workflows The real power of A2A comes when you connect multiple agents. Let's build a research assistant workflow: ```python from python_a2a import ( A2AClient, Message, TextContent, MessageRole, Conversation ) def research_workflow(query): # Connect to the specialized agents llm_client = A2AClient("http://localhost:5002/a2a") # LLM agent search_client = A2AClient("http://localhost:5003/a2a") # Search agent summarize_client = A2AClient("http://localhost:5004/a2a") # Summarize agent # Track the entire workflow in a conversation conversation = Conversation() conversation.create_text_message( text=f"Research question: {query}", role=MessageRole.USER ) # Step 1: Generate search queries print("Generating search queries...") search_request = Message( content=TextContent( text=f"Based on this research question: '{query}', " f"generate 3 specific search queries that would help find relevant information." ), role=MessageRole.USER ) search_queries_response = llm_client.send_message(search_request) conversation.add_message(search_queries_response) # Step 2: Retrieve information print("Retrieving information...") search_message = Message( content=TextContent( text=f"Search for information to answer: {query}\n\n" f"Using these queries:\n{search_queries_response.content.text}" ), role=MessageRole.USER ) search_results = search_client.send_message(search_message) conversation.add_message(search_results) # Step 3: Synthesize information print("Synthesizing information...") summarize_message = Message( content=TextContent( text=f"Synthesize this information to answer the question: '{query}'\n\n" f"Information:\n{search_results.content.text}" ), role=MessageRole.USER ) summary_response = summarize_client.send_message(summarize_message) conversation.add_message(summary_response) # Add final answer to the conversation conversation.create_text_message( text=f"Answer to your research question:\n\n{summary_response.content.text}", role=MessageRole.AGENT ) return conversation # Example usage if __name__ == "__main__": query = input("What's your research question? ") result = research_workflow(query) print("\nResearch Complete!") print("=" * 50) print(result.messages[-1].content.text) ``` ## Advanced Example: Weather and Trip Planning with A2A Here's an example demonstrating how A2A simplifies communication between agents: ```python from python_a2a import A2AClient, Message, TextContent, MessageRole # With A2A: Any agent -> Any other agent def plan_trip(location): # Connect to specialized agents - all using the same protocol weather_client = A2AClient("http://localhost:5001/a2a") openai_client = A2AClient("http://localhost:5002/a2a") # Ask weather agent weather_message = Message( content=TextContent(text=f"What's the weather forecast for {location}?"), role=MessageRole.USER ) weather_response = weather_client.send_message(weather_message) # Ask OpenAI agent, including weather info planning_message = Message( content=TextContent( text=f"I'm planning a trip to {location}. Weather forecast: {weather_response.content.text}" f"Please suggest activities." ), role=MessageRole.USER ) planning_response = openai_client.send_message(planning_message) return planning_response.content.text # This works with ANY A2A-compatible agents - no custom adapters needed! ``` ## Managing Conversations Python A2A provides a `Conversation` class to manage multi-turn interactions: ```python from python_a2a import Conversation, MessageRole, A2AClient # Create a new conversation conversation = Conversation() # Add a user message conversation.create_text_message( text="What's the weather like today?", role=MessageRole.USER ) # Connect to an agent weather_agent = A2AClient("http://localhost:5001/a2a") # Send the last message in the conversation last_message = conversation.messages[-1] response = weather_agent.send_message(last_message) # Add the response to the conversation conversation.add_message(response) # Continue the conversation conversation.create_text_message( text="Thanks! Will I need an umbrella?", role=MessageRole.USER ) # Send the new message, including conversation history response = weather_agent.send_message( conversation.messages[-1], conversation_id=conversation.conversation_id ) # Add this response too conversation.add_message(response) # Print the entire conversation for msg in conversation.messages: role = "User" if msg.role == MessageRole.USER else "Agent" print(f"{role}: {msg.content.text}") ``` ## Error Handling Python A2A provides standardized error handling: ```python from python_a2a import A2AClient, Message, TextContent, MessageRole client = A2AClient("http://localhost:5001/a2a") try: message = Message( content=TextContent(text="Hello"), role=MessageRole.USER ) response = client.send_message(message) except ConnectionError as e: print(f"Connection error: {e}") except TimeoutError as e: print(f"Timeout error: {e}") except Exception as e: print(f"Unexpected error: {e}") ``` ## Creating Custom A2A Agents Here's a template for creating your own A2A-compatible agent: ```python from python_a2a import A2AServer, Message, TextContent, MessageRole, run_server class MyCustomAgent(A2AServer): def __init__(self, **kwargs): super().__init__(**kwargs) # Initialize your agent-specific components here def handle_message(self, message): """Process incoming messages and return responses. This is the main entry point for handling messages in your agent. """ if message.content.type == "text": # Process text messages user_text = message.content.text # Generate your response (replace with your logic) response_text = f"You said: {user_text}" return Message( content=TextContent(text=response_text), role=MessageRole.AGENT, parent_message_id=message.message_id, conversation_id=message.conversation_id ) elif message.content.type == "function_call": # Handle function calls (if your agent supports them) # ... pass # Return a default response if no other conditions matched return Message( content=TextContent(text="I don't know how to handle this message type."), role=MessageRole.AGENT, parent_message_id=message.message_id, conversation_id=message.conversation_id ) # Run your agent if __name__ == "__main__": my_agent = MyCustomAgent() run_server(my_agent, host="0.0.0.0", port=5005) ``` ## Conclusion Python A2A provides a standardized way for AI agents to communicate, making it easier to build multi-agent systems. By adopting this protocol, you can: 1. Reduce development time spent on communication infrastructure 2. Easily swap and upgrade agent implementations 3. Build modular, extensible AI systems 4. Leverage specialized agents for different tasks The A2A protocol and its Python implementation are helping to build a future where AI systems can be composed like LEGO blocks, with specialized agents working together seamlessly. For more information, check out the Python A2A GitHub repository, PyPI page, and documentation. ## /docs/understanding-a2a-protocol.md # Understanding A2A Protocol: A Comprehensive Guide The A2A Protocol represents a significant advancement in the field of AI agent interoperability. This guide will walk you through the core concepts, benefits, and practical applications of this groundbreaking technology. ## What is A2A Protocol? A2A Protocol is an open standard that enables AI agents to communicate and collaborate across different platforms and frameworks. It's designed to maximize the benefits of agentic AI by enabling true multi-agent scenarios. ### Key Features 1. **Universal Interoperability** - Enables agents to work together seamlessly - Platform and framework agnostic - Supports various AI models and architectures 2. **Enterprise-Grade Security** - Built-in authentication and authorization - Support for OpenAPI authentication schemes - End-to-end encryption 3. **Flexible & Scalable** - Supports quick tasks to long-running research - Real-time feedback and state updates - Distributed architecture ## Benefits of A2A Protocol The A2A Protocol offers numerous advantages for organizations and developers: - **Reduced Development Time**: No need to build custom integration solutions - **Enhanced Collaboration**: Seamless communication between different AI systems - **Future-Proof**: Designed to evolve with the AI landscape - **Cost-Effective**: Leverage existing AI investments ## Getting Started To begin using the A2A Protocol: 1. Review the [documentation](https://google.github.io/A2A/#/) 2. Explore the [code samples](https://github.com/google/A2A/tree/main/samples) 3. Join the [community](https://github.com/google/A2A/discussions) ## Conclusion The A2A Protocol is revolutionizing how AI agents interact and collaborate. By adopting this standard, organizations can unlock new possibilities in AI development and deployment. Stay tuned for more articles in our series, where we'll dive deeper into specific aspects of the A2A Protocol and its implementation. ## /images/a2a-directory.png Binary file available at https://raw.githubusercontent.com/sing1ee/a2a-directory/refs/heads/main/images/a2a-directory.png ## /images/a2a-directory.svg ```svg path="/images/a2a-directory.svg" ``` ## /images/a2a-guide-typescript.png Binary file available at https://raw.githubusercontent.com/sing1ee/a2a-directory/refs/heads/main/images/a2a-guide-typescript.png ## /images/a2a-protocol.png Binary file available at https://raw.githubusercontent.com/sing1ee/a2a-directory/refs/heads/main/images/a2a-protocol.png ## /images/awesome-badge.svg ```svg path="/images/awesome-badge.svg" ``` ## /images/header.svg ```svg path="/images/header.svg" ``` ## /images/prs-welcome.svg ```svg path="/images/prs-welcome.svg" ``` ## /images/thumbnail.svg ```svg path="/images/thumbnail.svg" ``` ## /llms.txt # A2A Directory Project Overview The A2A Directory is a comprehensive resource hub for the Agent2Agent (A2A) protocol, an open standard initiated by Google that enables communication and interoperability between AI agent systems. This directory serves as a central repository for A2A-related resources, implementations, and community contributions. ## 1. Project Overview * **Project Name:** A2A Directory * **Purpose:** A centralized resource hub for the A2A protocol ecosystem * **Core Goal:** Provide comprehensive documentation, implementation examples, and community resources for A2A protocol adoption * **Key Features:** * Multi-language documentation (English, Chinese, Japanese, German) * Community implementation showcase * Framework integration guides * Resource aggregation ## 2. Core Components ### 2.1. Documentation * **Technical Documentation:** Links to official A2A protocol documentation * **JSON Specification:** Reference to the A2A protocol JSON schema * **Agent Card Specification:** Guidelines for creating Agent Cards * **Community Guides:** * TypeScript implementation guide * A2A vs MCP comparison * Protocol deep dive * Sample methods and responses * Python implementation guide ### 2.2. Implementations #### Official Samples * **Python:** * Common Library: Core HTTP, JSON-RPC, SSE handling * Host (Client): Command-line client example * Host (Agent): Orchestrator agent implementation * **JavaScript/TypeScript:** * Server Library: Core server implementation * Client Library: Client implementation * Host (Client): Command-line client example #### Framework Integrations * **Python:** * LangGraph: Currency conversion with tools, streaming, multi-turn * CrewAI: Image generation with file artifacts * Google ADK: Expense reimbursement with forms * **JavaScript/TypeScript:** * Genkit: Movie info and code generation ### 2.3. Community Resources #### Community Implementations * **TypeScript:** * legion-a2a: Modular and extensible implementation * nestjs-a2a: NestJS integration module * **Go:** * a2a-go: Go library for A2A servers * **Rust:** * a2a-rs: Idiomatic Rust implementation * **Python:** * a2a_min: Minimalistic Python SDK * python-a2a: Easy-to-use implementation * **C#/.NET:** * a2adotnet: C# implementation * **Other:** * Aira: A2A network implementation * Cognisphere: AI agent development framework * Grasp: Browser agent with A2A support ## 3. Getting Started 1. **Learn the Basics** * Read the technical documentation * Watch the demo video * Explore the JSON specification 2. **Choose Implementation** * Select preferred language/framework * Review relevant documentation * Study sample implementations 3. **Community Engagement** * Join GitHub discussions * Report issues * Contribute implementations ## 4. Resources ### Official Resources * Website: google.github.io/A2A * GitHub: github.com/google/A2A * Documentation: Technical docs, JSON spec, Agent Card spec ### Community Resources * TypeScript Guide * A2A vs MCP comparison * Protocol deep dive * Sample methods and responses * Python implementation guide ## 5. Community * GitHub Issues: Bug reports and feature requests * GitHub Discussions: Community discussions * Contributing Guidelines: How to contribute to the project ## 6. Contribution The project welcomes contributions from the community. Please refer to the CONTRIBUTING.md file for guidelines on: * Code contributions * Documentation updates * Bug reports * Feature requests * Community support The better and more specific the context, the better the LLM can follow instructions. If the context seems verbose, the user can refine the filter using uithub. Thank you for using https://uithub.com - Perfect LLM context for any GitHub repo.