a2a 0.1.0.pre → 0.2.0

data/.agent-docs/tutorials/python/7-streaming-and-multiturn.md

@@ -0,0 +1,97 @@
+# 7. Streaming & Multi-Turn Interactions (LangGraph Example)
+
+The Helloworld example demonstrates the basic mechanics of A2A. For more advanced features like robust streaming, task state management, and multi-turn conversations powered by an LLM, we'll turn to the LangGraph example located in [`a2a-samples/samples/python/agents/langgraph/`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/langgraph).
+
+This example features a "Currency Agent" that uses the Gemini model via LangChain and LangGraph to answer currency conversion questions.
+
+## Setting up the LangGraph Example
+
+1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key), if you don't already have one.
+
+2. **Environment Variable:**
+
+    Create a `.env` file in the `a2a-samples/samples/python/agents/langgraph/` directory:
+
+    ```bash
+    echo "GOOGLE_API_KEY=YOUR_API_KEY_HERE" > .env
+    ```
+
+    Replace `YOUR_API_KEY_HERE` with your actual Gemini API key.
+
+3. **Install Dependencies (if not already covered):**
+
+    The `langgraph` example has its own `pyproject.toml` which includes dependencies like `langchain-google-genai` and `langgraph`. When you installed the SDK from the `a2a-samples` root using `pip install -e .[dev]`, this should have also installed the dependencies for the workspace examples, including `langgraph-example`. If you encounter import errors, ensure your primary SDK installation from the root directory was successful.
+
+## Running the LangGraph Server
+
+Navigate to the `a2a-samples/samples/python/agents/langgraph/app` directory in your terminal and ensure your virtual environment (from the SDK root) is activated.
+
+Start the LangGraph agent server:
+
+```bash
+python __main__.py
+```
+
+This will start the server, usually on `http://localhost:10000`.
+
+## Interacting with the LangGraph Agent
+
+Open a **new terminal window**, activate your virtual environment, and navigate to `a2a-samples/samples/python/agents/langgraph/app`.
+
+Run its test client:
+
+```bash
+python test_client.py
+```
+
+Now, you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running.
+
+## Key Features Demonstrated
+
+The `langgraph` example showcases several important A2A concepts:
+
+1. **LLM Integration**:
+
+    - `agent.py` defines `CurrencyAgent`. It uses `ChatGoogleGenerativeAI` and LangGraph's `create_react_agent` to process user queries.
+    - This demonstrates how a real LLM can power the agent's logic.
+
+2. **Task State Management**:
+
+    - `samples/langgraph/__main__.py` initializes a `DefaultRequestHandler` with an `InMemoryTaskStore`.
+
+        ```python { .no-copy }
+        --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/langgraph/app/__main__.py:DefaultRequestHandler"
+        ```
+
+    - The `CurrencyAgentExecutor` (in `samples/langgraph/agent_executor.py`), when its `execute` method is called by the `DefaultRequestHandler`, interacts with the `RequestContext` which contains the current task (if any).
+    - For `message/send`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `message/send` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
+    - The `test_client.py`'s `run_single_turn_test` demonstrates getting a `Task` object back and then querying it using `get_task`.
+
+3. **Streaming with `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`**:
+
+    - The `execute` method in `CurrencyAgentExecutor` is responsible for handling both non-streaming and streaming requests, orchestrated by the `DefaultRequestHandler`.
+    - As the LangGraph agent processes the request (which might involve calling tools like `get_exchange_rate`), the `CurrencyAgentExecutor` enqueues different types of events onto the `EventQueue`:
+        - `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates.."). The `final` flag on these events is `False`.
+        - `TaskArtifactUpdateEvent`: When the final answer is ready, it's enqueued as an artifact. The `lastChunk` flag is `True`.
+        - A final `TaskStatusUpdateEvent` with `state=TaskState.completed` and `final=True` is sent to signify the end of the task for streaming.
+    - The `test_client.py`'s `run_streaming_test` function will print these individual event chunks as they are received from the server.
+
+4. **Multi-Turn Conversation (`TaskState.input_required`)**:
+
+    - The `CurrencyAgent` can ask for clarification if a query is ambiguous (e.g., user asks "how much is 100 USD?").
+    - When this happens, the `CurrencyAgentExecutor` will enqueue a `TaskStatusUpdateEvent` where `status.state` is `TaskState.input_required` and `status.message` contains the agent's question (e.g., "To which currency would you like to convert?"). This event will have `final=True` for the current interaction stream.
+    - The `test_client.py`'s `run_multi_turn_test` function demonstrates this:
+        - It sends an initial ambiguous query.
+        - The agent responds (via the `DefaultRequestHandler` processing the enqueued events) with a `Task` whose status is `input_required`.
+        - The client then sends a second message, including the `taskId` and `contextId` from the first turn's `Task` response, to provide the missing information ("in GBP"). This continues the same task.
+
+## Exploring the Code
+
+Take some time to look through these files:
+
+- `__main__.py`: Server setup using `A2AStarletteApplication` and `DefaultRequestHandler`. Note the `AgentCard` definition includes `capabilities.streaming=True`.
+- `agent.py`: The `CurrencyAgent` with LangGraph, LLM model, and tool definitions.
+- `agent_executor.py`: The `CurrencyAgentExecutor` implementing the `execute` (and `cancel`) method. It uses the `RequestContext` to understand the ongoing task and the `EventQueue` to send back various events (`TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`, new `Task` object implicitly via the first event if no task exists).
+- `test_client.py`: Demonstrates various interaction patterns, including retrieving task IDs and using them for multi-turn conversations.
+
+This example provides a much richer illustration of how A2A facilitates complex, stateful, and asynchronous interactions between agents.

data/.agent-docs/tutorials/python/8-next-steps.md

@@ -0,0 +1,40 @@
+# Next Steps
+
+Congratulations on completing the A2A Python SDK Tutorial! You've learned how to:
+
+- Set up your environment for A2A development.
+- Define Agent Skills and Agent Cards using the SDK's types.
+- Implement a basic HelloWorld A2A server and client.
+- Understand and implement streaming capabilities.
+- Integrate a more complex agent using LangGraph, demonstrating task state management and tool use.
+
+You now have a solid foundation for building and integrating your own A2A-compliant agents.
+
+## Where to Go From Here?
+
+Here are some ideas and resources to continue your A2A journey:
+
+- **Explore Other Examples:**
+    - Check out the other examples in the [a2a-samples GitHub repository](https://github.com/a2aproject/a2a-samples/tree/main/samples) for more complex agent integrations and features.
+- **Deepen Your Protocol Understanding:**
+    - 📚 Read the complete [A2A Protocol Documentation site](https://a2a-protocol.org) for a comprehensive overview.
+    - 📝 Review the detailed [A2A Protocol Specification](../../specification.md) to understand the nuances of all data structures and RPC methods.
+- **Review Key A2A Topics:**
+    - [A2A and MCP](../../topics/a2a-and-mcp.md): Understand how A2A complements the Model Context Protocol for tool usage.
+    - [Enterprise-Ready Features](../../topics/enterprise-ready.md): Learn about security, observability, and other enterprise considerations.
+    - [Streaming & Asynchronous Operations](../../topics/streaming-and-async.md): Get more details on SSE and push notifications.
+    - [Agent Discovery](../../topics/agent-discovery.md): Explore different ways agents can find each other.
+- **Build Your Own Agent:**
+    - Try creating a new A2A agent using your favorite Python agent framework (like LangChain, CrewAI, AutoGen, Semantic Kernel, or a custom solution).
+    - Implement the `a2a.server.AgentExecutor` interface to bridge your agent's logic with the A2A protocol.
+    - Think about what unique skills your agent could offer and how its Agent Card would represent them.
+- **Experiment with Advanced Features:**
+    - Implement robust task management with a persistent `TaskStore` if your agent handles long-running or multi-session tasks.
+    - Explore implementing push notifications if your agent's tasks are very long-lived.
+    - Consider more complex input and output modalities (e.g., handling file uploads/downloads, or structured data via `DataPart`).
+- **Contribute to the A2A Community:**
+    - Join the discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).
+    - Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).
+    - Consider contributing code, examples, or documentation. See the [CONTRIBUTING.md](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md) guide.
+
+The A2A protocol aims to foster an ecosystem of interoperable AI agents. By building and sharing A2A-compliant agents, you can be a part of this exciting development!