### Start A2AServer Example

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/03-a2a-server.md

Demonstrates how to create an AgentCard, instantiate a TaskManager, configure and start the A2AServer. Ensure both agent_card and task_manager are provided before starting.

```python
from common.server import A2AServer
from common.types import AgentCard, AgentCapabilities, AgentSkill

card = AgentCard(
    name="my_agent",
    description="An example agent",
    url="http://localhost:5000/",
    version="1.0.0",
    capabilities=AgentCapabilities(streaming=True),
    skills=[
        AgentSkill(
            id="skill1",
            name="Do Something",
            description="An example skill"
        )
    ]
)

manager = MyTaskManager()  # Implements TaskManager

server = A2AServer(
    host="0.0.0.0",
    port=8000,
    endpoint="/tasks",
    agent_card=card,
    task_manager=manager,
)

server.start()  # Blocks until server stops
```

--------------------------------

### Install Node.js and npm on Ubuntu

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Use apt-get to install Node.js and npm on Ubuntu systems.

```bash
# Ubuntu
sudo apt-get install nodejs npm
```

--------------------------------

### Example Root .env File Configuration

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

An example demonstrating how to configure Google AI, Notion, LinkedIn, and Vertex AI settings in the root .env file.

```env
# Google AI
GOOGLE_API_KEY=AIzaSyDxxx...

# Or Google Cloud
GOOGLE_CLOUD_PROJECT=my-gcp-project
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# Notion
NOTION_API_KEY=secret_xxx...

# LinkedIn (Proxycurl)
PROXYCURL_API_KEY=pyCurl_xxx...

# Optional
# VERTEX_AI_CODE_EXECUTOR_RESOURCE_NAME=projects/123/locations/us-central1/extensions/456
```

--------------------------------

### Start A2A Server

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/04-agent-implementations.md

Initializes and starts the A2AServer with specified host, port, agent card, and task manager. Requires configurations for agent card and task manager.

```python
from common.server import A2AServer
from common.types import AgentCard, AgentCapabilities, AgentSkill

server = A2AServer(
    host="0.0.0.0",
    port=10000,
    agent_card=AgentCard(...),
    task_manager=MyTaskManager(...)
)
server.start()
```

--------------------------------

### Example .env File Structure

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

An example of how to structure your .env file in the root of the commit-adk project, including keys for Notion, Proxycurl, and Google AI.

```env
# commit-adk/.env

# Notion
NOTION_API_KEY="secret_..."

# LinkedIn (via Proxycurl)
PROXYCURL_API_KEY="your_proxycurl_api_key"

# Optional: Google AI (Gemini API Key from AI Studio is often sufficient)
GOOGLE_API_KEY="your_gemini_api_key_from_ai_studio"

# Optional: If using Google Cloud Platform specific services
# GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# Optional: To force non-Vertex AI for Gemini models if both API key and ADC are available
# GOOGLE_GENAI_USE_VERTEXAI="FALSE"
```

--------------------------------

### Start All Agents Locally

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

Starts all 6 agents on ports 10000-10005 with unified logging. Navigate to the project directory before running.

```bash
cd /workspace/home/commit-adk
python run_all_agents.py
```

--------------------------------

### Test npx Installation

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Verify the installation of npx by checking its version.

```bash
# Then test
npx @notionhq/notion-mcp-server --version
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Use this command to install project dependencies from a requirements file.

```bash
pip install -r requirements.txt
```

--------------------------------

### A2AServer.start()

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/03-a2a-server.md

Starts the A2A HTTP server, making it ready to handle incoming requests.

```APIDOC
## A2AServer.start()

### Description
Starts the HTTP server. The server will listen on the configured `host:port` and register two routes: `POST {endpoint}` for A2A protocol requests and `GET /.well-known/agent.json` for the agent card.

### Signature
```python
def start()
```

### Parameters
None

### Request Example
```python
from common.server import A2AServer
from common.types import AgentCard, AgentCapabilities, AgentSkill

card = AgentCard(
    name="my_agent",
    description="An example agent",
    url="http://localhost:5000/",
    version="1.0.0",
    capabilities=AgentCapabilities(streaming=True),
    skills=[
        AgentSkill(
            id="skill1",
            name="Do Something",
            description="An example skill"
        )
    ]
)

manager = MyTaskManager()  # Implements TaskManager

server = A2AServer(
    host="0.0.0.0",
    port=8000,
    endpoint="/tasks",
    agent_card=card,
    task_manager=manager,
)

server.start()  # Blocks until server stops
```

### Response
None

### Raises
- `ValueError`: If `agent_card` is not set
- `ValueError`: If `task_manager` is not set
```

--------------------------------

### Install Node.js and npx on macOS

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Use Homebrew to install Node.js and npx on macOS systems.

```bash
# macOS
brew install node
```

--------------------------------

### Agent Compatibility Testing Example

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

This example tests an agent's compatibility, including streaming support, input/output modes, and basic connectivity. It iterates through a list of agent URLs to perform these tests.

```python
import asyncio
from common.client import A2AClient, A2ACardResolver
from common.types import ContentTypeNotSupportedError

async def test_agent_compatibility(agent_url: str):
    """Test if an agent supports streaming and specific content types"""
    
    try:
        # Get agent card
        resolver = A2ACardResolver(agent_url)
        card = resolver.get_agent_card()
        
        print(f"Agent: {card.name}")
        print(f"  Supports streaming: {card.capabilities.streaming}")
        print(f"  Supports push notifications: {card.capabilities.pushNotifications}")
        print(f"  Input modes: {card.defaultInputModes}")
        print(f"  Output modes: {card.defaultOutputModes}")
        
        # Test basic connectivity
        client = A2AClient(agent_card=card)
        response = await client.send_task({
            "id": "test-ping",
            "message": {"role": "user", "parts": [{"type": "text", "text": "Hello"}]},
            "acceptedOutputModes": ["text"],
        })
        
        if response.result:
            print(f"  Status: ✓ Working")
        else:
            print(f"  Status: ✗ Error - {response.error.message}")
    
    except Exception as e:
        print(f"Agent {agent_url}: ✗ Unreachable - {e}")

# Test all agents
async def test_all():
    agents = [
        "http://localhost:10000",
        "http://localhost:10001",
        "http://localhost:10002",
        "http://localhost:10003",
        "http://localhost:10004",
    ]
    
    for url in agents:
        await test_agent_compatibility(url)
        print()

asyncio.run(test_all())
```

--------------------------------

### Set Up Python Virtual Environment

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Create and activate a Python virtual environment, then install project dependencies using pip.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Get Push Notification Config Response

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Example response showing the configured push notification details for a task.

```json
{
  "jsonrpc": "2.0",
  "id": "req-128",
  "result": {
    "id": "task-001",
    "pushNotificationConfig": {
      "url": "https://myservice.com/webhook",
      "token": "secret-token"
    }
  }
}
```

--------------------------------

### Start ADK Web UI

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Launches the ADK Web UI. The command provides a URL, typically http://localhost:8080, to access the UI in a web browser.

```bash
adk web
```

--------------------------------

### Run Google Calendar Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Starts the Google Calendar A2A agent as a separate service.

```bash
python -m agents.google_calendar
```

--------------------------------

### Run LinkedIn Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Starts the LinkedIn A2A agent as a separate service.

```bash
python -m agents.linkedin
```

--------------------------------

### Get Task Status Response

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Example response when a task status is successfully retrieved, including its state and history.

```json
{
  "jsonrpc": "2.0",
  "id": "req-125",
  "result": {
    "id": "task-001",
    "sessionId": "session-abc",
    "status": {
      "state": "completed",
      "message": {...},
      "timestamp": "2025-06-24T10:30:00Z"
    },
    "artifacts": [...],
    "history": [...] 
  }
}
```

--------------------------------

### Start All A2A Agents

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/05-orchestrators.md

Command to initiate all necessary agents for the A2A orchestrator. Ensure all agents are running before proceeding.

```bash
python run_all_agents.py
```

--------------------------------

### Run Python Developer Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Starts the Python Developer A2A agent as a separate service.

```bash
python -m agents.python_developer
```

--------------------------------

### Run Notion Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Starts the Notion A2A agent as a separate service. This agent requires npx @notionhq/notion-mcp-server to be runnable.

```bash
python -m agents.notion
```

--------------------------------

### Notion Integration Example

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

This snippet demonstrates how to create a new Notion page with specific sections using the A2AClient. Ensure the Notion agent is running at http://localhost:10004/.

```python
import asyncio
from common.client import A2AClient
from common.types import Message, TextPart

async def update_notion():
    client = A2AClient(url="http://localhost:10004/")  # Notion agent
    
    response = await client.send_task({
        "id": "notion-task",
        "message": Message(
            role='user',
            parts=[TextPart(text="""
                Create a new Notion page titled "Project Meeting Notes" 
                with the following sections:
                - Attendees
                - Topics Discussed
                - Action Items
                - Next Steps
            """)].model_dump(),
    })
    
    print(response.result.status.message.parts[0].text)

asyncio.run(update_notion())
```

--------------------------------

### Configure Push Notification Response

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Example response confirming the push notification configuration for a task.

```json
{
  "jsonrpc": "2.0",
  "id": "req-127",
  "result": {
    "id": "task-001",
    "pushNotificationConfig": {
      "url": "https://myservice.com/webhook",
      "token": "secret-token",
      "authentication": {...}
    }
  }
}
```

--------------------------------

### Reduce Model Thinking Budget

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Configure the `BuiltInPlanner` with a reduced `thinking_budget` to decrease model response time. This example reduces the budget to 2000 units.

```python
planner=BuiltInPlanner(
    thinking_config=ThinkingConfig(
        include_thoughts=True,
        thinking_budget=2000  # Reduced from 5000-8000
    )
)
```

--------------------------------

### Navigate to agents directory

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Changes the current directory to the 'agents' folder. This is a prerequisite for starting the ADK Web UI.

```bash
cd agents
```

--------------------------------

### Run A2A Orchestrator

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Ensure agents are running, then start the A2A orchestrator web interface. Select 'a2a_orchestrator' from the dropdown at http://localhost:8080.

```bash
# First, ensure agents are running (from step 1 or 2)
cd agents
adk web
```

--------------------------------

### Configure httpx Connection Limits

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Control the maximum number of concurrent connections for the `httpx.AsyncClient` using `httpx.Limits`. This example sets the maximum connections to 10.

```python
async with httpx.AsyncClient(limits=httpx.Limits(max_connections=10)) as client:
    response = await client.post(...)
```

--------------------------------

### Run Deep Research Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Starts the Deep Research A2A agent as a separate service.

```bash
python -m agents.deep_research
```

--------------------------------

### Run Python Developer Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

This command initiates the Python Developer agent. It's used during the setup process for the Vertex AI Code Executor to create a new extension.

```bash
cd agents && adk run python_developer
```

--------------------------------

### Create Custom Agent Wrapper

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

Implement a custom agent wrapper class that conforms to the A2A interface, supporting both synchronous invocation and asynchronous streaming of responses. This example demonstrates session management and content handling.

```python
# agents/my_agent/a2a_agent_wrapper.py

from typing import Any
from collections.abc import AsyncIterable
from .agent import root_agent, runner

class MyAgentA2AWrapper:
    SUPPORTED_CONTENT_TYPES = ["text"]
    
    def __init__(self):
        self._agent = root_agent
        self._runner = runner
        self._user_id = "a2a_user"
    
    def invoke(self, query: str, session_id: str) -> str:
        """Execute query and return complete response"""
        
        session = self._runner.session_service.get_session(
            app_name=self._runner.app_name,
            user_id=self._user_id,
            session_id=session_id,
        )
        
        if session is None:
            session = self._runner.session_service.create_session(
                app_name=self._runner.app_name,
                user_id=self._user_id,
                state={},
                session_id=session_id,
            )
        
        from google.genai import types
        user_content = types.Content(
            role='user',
            parts=[types.Part.from_text(text=query)]
        )
        
        events = list(self._runner.run(
            user_id=self._user_id,
            session_id=session.id,
            new_message=user_content,
        ))
        
        if not events or not events[-1].content:
            return "No response generated"
        
        return '\n'.join(
            p.text for p in events[-1].content.parts if p.text
        )
    
    async def stream(self, query: str, session_id: str) -> AsyncIterable[dict[str, Any]]:
        """Stream response progressively"""
        
        session = self._runner.session_service.get_session(
            app_name=self._runner.app_name,
            user_id=self._user_id,
            session_id=session_id,
        )
        
        if session is None:
            session = self._runner.session_service.create_session(
                app_name=self._runner.app_name,
                user_id=self._user_id,
                state={},
                session_id=session_id,
            )
        
        from google.genai import types
        user_content = types.Content(
            role='user',
            parts=[types.Part.from_text(text=query)]
        )
        
        async for event in self._runner.run_async(
            user_id=self._user_id,
            session_id=session.id,
            new_message=user_content,
        ):
            if event.is_final_response():
                content = ''
                if event.content:
                    content = '\n'.join(
                        p.text for p in event.content.parts if p.text
                    )
                
                yield {
                    'is_task_complete': True,
                    'content': content,
                }
            elif event.content:
                intermediate = '\n'.join(
                    p.text for p in event.content.parts if p.text
                )
                yield {
                    'is_task_complete': False,
                    'updates': intermediate,
                }
```

--------------------------------

### Monitor A2A Requests with Network Tools

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Demonstrates how to monitor A2A requests by running the agent in one terminal and using curl in others to inspect traffic and send tasks. This setup is useful for debugging network interactions.

```bash
# Terminal 1: Start agent
python -m agents.python_developer

# Terminal 2: Monitor requests
curl -v http://localhost:10000/.well-known/agent.json

# Terminal 3: Send task
curl -X POST http://localhost:10000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "tasks/send",
    "params": {
      "id": "task-1",
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Hello"}]
      }
    }
  }' | jq .
```

--------------------------------

### tasks/send Response - Task Execution Result

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

This is an example of a successful response after executing a task via the 'tasks/send' method. It includes task status, results, and history.

```json
{
  "jsonrpc": "2.0",
  "id": "req-123",
  "result": {
    "id": "task-001",
    "sessionId": "session-abc",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [
          {"type": "text", "text": "def sort_list(items): ..."}
        ]
      },
      "timestamp": "2025-06-24T10:30:00Z"
    },
    "artifacts": [
      {
        "name": "code",
        "parts": [
          {"type": "text", "text": "def sort_list(items): ..."}
        ]
      }
    ],
    "history": [
      {"role": "user", "parts": [...]},
      {"role": "agent", "parts": [...]} 
    ]
  }
}
```

--------------------------------

### A2AServer Constructor

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/03-a2a-server.md

Initializes the A2AServer with network configuration, an agent card, and a task manager.

```APIDOC
## A2AServer Constructor

### Description
Initializes the A2AServer with network configuration, an agent card, and a task manager.

### Signature
```python
def __init__(
    self,
    host: str = '0.0.0.0',
    port: int = 5000,
    endpoint: str = '/',
    agent_card: AgentCard = None,
    task_manager: TaskManager = None,
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| host | str | '0.0.0.0' | Network interface to bind to |
| port | int | 5000 | Port number for the server |
| endpoint | str | '/' | HTTP path where A2A requests are handled |
| agent_card | AgentCard \| None | None | Agent metadata describing this agent's capabilities |
| task_manager | TaskManager \| None | None | Handler for incoming A2A requests |

### Notes
Both `agent_card` and `task_manager` must be provided before calling `start()`.
```

--------------------------------

### Get Agent Card

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/02-a2a-client.md

Fetch and parse the agent card from a remote agent. This method handles constructing the full URL, making the GET request, and parsing the JSON response into an AgentCard model. It raises httpx.HTTPError for request failures and A2AClientJSONError for invalid JSON.

```python
def get_agent_card(self) -> AgentCard
```

```python
from common.client import A2ACardResolver

resolver = A2ACardResolver(base_url="http://localhost:10000")
card = resolver.get_agent_card()

print(f"Agent: {card.name}")
print(f"Version: {card.version}")
print(f"Capabilities: {card.capabilities.model_dump()}")

for skill in card.skills:
    print(f"  - {skill.name}: {skill.description}")
```

--------------------------------

### Initialize A2AClient

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/02-a2a-client.md

Instantiate the A2AClient with either agent metadata or a direct URL. Ensure either agent_card or url is provided.

```python
from common.client import A2AClient
from common.types import AgentCard, TimeoutTypes

# Example using URL
client_by_url = A2AClient(url="http://localhost:10000/")

# Example using AgentCard (assuming agent_card is defined)
# agent_card = AgentCard(...)
# client_by_card = A2AClient(agent_card=agent_card)

# Example with custom timeout
# client_with_timeout = A2AClient(url="http://localhost:10000/", timeout=TimeoutTypes(connect=5.0, read=10.0))

```

--------------------------------

### Cancel Task Response

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Example response indicating a task has been successfully canceled.

```json
{
  "jsonrpc": "2.0",
  "id": "req-126",
  "result": {
    "id": "task-001",
    "status": {
      "state": "canceled",
      "timestamp": "2025-06-24T10:30:05Z"
    }
  }
}
```

--------------------------------

### Simple Task Execution Workflow

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Demonstrates a basic client-agent interaction for executing a task and receiving a completed status.

```text
Client → Agent: POST / {tasks/send: "task-1"}
Agent → Client: Response with Task(status: completed)
```

--------------------------------

### Discover Agent Capabilities

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

Connects to various agents and prints their name, description, streaming capabilities, and skills. Ensure agents are running before execution.

```python
import asyncio
from common.client import A2ACardResolver

async def discover_agents():
    agents = [
        ("Python Developer", "http://localhost:10000"),
        ("LinkedIn", "http://localhost:10001"),
        ("Calendar", "http://localhost:10002"),
        ("Research", "http://localhost:10003"),
        ("Notion", "http://localhost:10004"),
    ]
    
    for name, url in agents:
        try:
            resolver = A2ACardResolver(url)
            card = resolver.get_agent_card()
            
            print(f"\n{name}:")
            print(f"  Agent: {card.name}")
            print(f"  Description: {card.description}")
            print(f"  Streaming: {card.capabilities.streaming}")
            print(f"  Skills:")
            for skill in card.skills:
                print(f"    - {skill.name}: {skill.description}")
        except Exception as e:
            print(f"\n{name}: Failed to discover - {e}")

asyncio.run(discover_agents())
```

--------------------------------

### Agent Session and Artifact Management

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/04-agent-implementations.md

Sets up in-memory services for session and artifact management, and initializes a Runner for orchestrating agent execution.

```python
session_service = InMemorySessionService()
artifact_service = InMemoryArtifactService()
runner = Runner(
    agent=root_agent,
    session_service=session_service,
    artifact_service=artifact_service,
    app_name="agent_name",
)
```

--------------------------------

### Initialize A2ACardResolver

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/02-a2a-client.md

Instantiate the A2ACardResolver with the base URL of the remote agent and an optional path to the agent card. Trailing slashes from base_url and leading slashes from agent_card_path are automatically handled.

```python
def __init__(
    self,
    base_url: str,
    agent_card_path: str = '/.well-known/agent.json'
)
```

--------------------------------

### Get Push Notification Config Request

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Request the current webhook callback configuration for a specific task.

```json
{
  "jsonrpc": "2.0",
  "id": "req-128",
  "method": "tasks/pushNotification/get",
  "params": {
    "id": "task-001",
    "metadata": {}
  }
}
```

--------------------------------

### Configure Basic Logging

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/05-orchestrators.md

Sets up basic logging configuration for an application. This is useful for debugging orchestrator behavior by capturing agent decisions and task execution details.

```python
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
```

--------------------------------

### Get Task Status Request

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Send a request to retrieve the current status of a task, optionally limiting the history.

```json
{
  "jsonrpc": "2.0",
  "id": "req-125",
  "method": "tasks/get",
  "params": {
    "id": "task-001",
    "historyLength": 5,
    "metadata": {}
  }
}
```

--------------------------------

### Create Agent Method

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/05-orchestrators.md

Creates and returns the orchestrator's LlmAgent. This agent is configured with a specific model, name, instruction set, and tools for task management.

```python
def create_agent(self) -> Agent
```

--------------------------------

### Run ADK Web UI

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

Navigate to the agents directory and run the ADK web interface. This allows interaction with agents through a web UI.

```bash
cd agents
adk web
```

--------------------------------

### System Architecture Overview

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/README.md

Illustrates the flow of user requests through the Commit ADK system, from the orchestrator to specialized agents and external services.

```text
User Requests
    ↓
Orchestrator (ADK-Native or A2A)
    ├─ Task Decomposition
    ├─ Agent Selection
    └─ Result Aggregation
    ↓
Specialized Agents (via HTTP/RPC)
    ├─ Python Developer
    ├─ LinkedIn Intelligence
    ├─ Calendar Management
    ├─ Research & Analysis
    ├─ Notion Integration
    └─ Web Browsing
    ↓
External Services/APIs
    ├─ Google Gemini
    ├─ Proxycurl (LinkedIn)
    ├─ Google Calendar API
    └─ Notion API
```

--------------------------------

### InMemoryTaskManager Constructor

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/03-a2a-server.md

Initializes the internal data structures for storing tasks, notifications, and SSE subscribers. This is the starting point for the in-memory task management.

```python
def __init__(self)
```

--------------------------------

### Notion Integration Environment Variable

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Provide your Notion API key obtained from notion.com/my-integrations.

```env
# For Notion Agent - get from https://www.notion.com/my-integrations
NOTION_API_KEY=secret_<YOUR_NOTION_API_KEY>
```

--------------------------------

### Run Agent Module

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/04-agent-implementations.md

Executes the agent from its module directory using the python -m command.

```bash
python -m agents.my_agent
```

--------------------------------

### Task Status Update Event (Streaming)

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

An example of a Task Status Update Event received during streaming via 'tasks/sendSubscribe'. It includes the task state and a message.

```json
{
  "id": "task-002",
  "status": {
    "state": "working",
    "message": {
      "role": "agent",
      "parts": [{"type": "text", "text": "Processing..."}]
    },
    "timestamp": "2025-06-24T10:30:01Z"
  },
  "final": false
}
```

--------------------------------

### Send Task and Get Single Response

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/02-a2a-client.md

Use send_task to send a payload to an agent and await a single response. Handles potential HTTP or JSON errors.

```python
from common.client import A2AClient
from common.types import Message, TextPart

client = A2AClient(url="http://localhost:10000/")

response = await client.send_task({
    "id": "task-001",
    "sessionId": "session-001",
    "message": Message(
        role='user',
        parts=[TextPart(text="Write a Python function to sort a list")]
    ).model_dump(),
})

if response.result:
    print(f"Task completed: {response.result.id}")
elif response.error:
    print(f"Error: {response.error.message}")
```

--------------------------------

### A2AServer Constructor Signature

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/03-a2a-server.md

Defines the parameters for initializing the A2AServer, including host, port, endpoint, agent card, and task manager.

```python
def __init__(
    self,
    host: str = '0.0.0.0',
    port: int = 5000,
    endpoint: str = '/',
    agent_card: AgentCard = None,
    task_manager: TaskManager = None,
)
```

--------------------------------

### JSON-RPC Error with Additional Data

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

An example of a JSON-RPC error response that includes additional data, such as missing fields or validation errors, to help diagnose parameter issues.

```json
{
  "jsonrpc": "2.0",
  "id": "req-xxx",
  "error": {
    "code": -32602,
    "message": "Invalid parameters",
    "data": {
      "missing_field": "sessionId",
      "validation_errors": [...]
    }
  }
}
```

--------------------------------

### Task Artifact Update Event (Streaming)

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

An example of a Task Artifact Update Event received during streaming via 'tasks/sendSubscribe'. It details generated artifacts like code.

```json
{
  "id": "task-002",
  "artifact": {
    "name": "output",
    "description": "Generated code",
    "parts": [{"type": "text", "text": "..."}],
    "index": 0
  }
}
```

--------------------------------

### Authenticate with Google Cloud for Production

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Sets up Application Default Credentials for accessing Google Cloud services, including the Calendar API and Vertex AI. This is suitable for production environments.

```bash
gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/calendar
```

--------------------------------

### tasks/sendSubscribe Response - Streaming Updates

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Server-Sent Events for streaming task updates. Each event is a JSON object prefixed with 'data: '. This example shows a task status update.

```json
data: {"jsonrpc":"2.0","id":"req-124","result":{"id":"task-002","status":{"state":"working",...}}}
data: {"jsonrpc":"2.0","id":"req-124","result":{"id":"task-002","artifact":...}}
data: {"jsonrpc":"2.0","id":"req-124","result":{"id":"task-002","status":{"state":"completed","final":true}}}
```

--------------------------------

### Retrieve Task Push Notification Callback Configuration

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/02-a2a-client.md

Use this method to get the current push notification callback configuration for a specific task. The payload requires the task ID.

```python
response = await client.get_task_callback({"id": "task-001"})

if response.result:
    config = response.result.pushNotificationConfig
    print(f"Webhook URL: {config.url}")
```

--------------------------------

### Set Google API Key for AI Studio

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Configure your environment to use a Google API key obtained from Google AI Studio. This is recommended for development and provides access to Gemini models.

```env
GOOGLE_API_KEY=<YOUR_KEY>
```

--------------------------------

### Discover Agent and Send Task

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/02-a2a-client.md

Discover an agent's capabilities using A2ACardResolver, create an A2AClient, and send a task.

```python
from common.client import A2ACardResolver, A2AClient

# Step 1: Discover the agent's capabilities
resolver = A2ACardResolver("http://localhost:10000")
agent_card = resolver.get_agent_card()

# Step 2: Create a client for that agent
client = A2AClient(agent_card=agent_card)

# Step 3: Send a task
response = await client.send_task({
    "id": "my-task",
    "message": {...}
})
```

--------------------------------

### Process CSV Data with Developer Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

Utilize the Python Developer Agent to parse CSV data and calculate the average age. This example demonstrates handling structured data input.

```python
async def process_data():
    client = A2AClient(url="http://localhost:10000/")
    
    csv_data = """name,age,city
Alice,30,NYC
Bob,25,LA
Charlie,35,Chicago"""
    
    response = await client.send_task({
        "id": "data-process",
        "message": Message(
            role='user',
            parts=[TextPart(text=f"""
                Parse this CSV data and calculate average age:
                {csv_data}
            """)]
        ).model_dump(),
    })
    
    print(response.result.status.message.parts[0].text)

asyncio.run(process_data())
```

--------------------------------

### Add New Remote Agent Address to A2A Orchestrator

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/05-orchestrators.md

Example of how to add a new remote agent's address to the A2A orchestrator's configuration in Python. This allows the HostAgent to discover and utilize the new agent.

```python
new_agent_address = "http://host:port"

root_agent = HostAgent([
    ...existing addresses…,
    new_agent_address
]).create_agent()
```

--------------------------------

### Implement Custom Task Manager

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/03-a2a-server.md

Provides a base class for creating custom task managers, demonstrating how to handle task sending requests, validate input, execute an agent, and manage task status updates.

```python
from common.server import InMemoryTaskManager
from common.types import (
    SendTaskRequest, SendTaskResponse, SendTaskStreamingRequest,
    TaskSendParams, TextPart, TaskStatus, TaskState, Message
)

class MyTaskManager(InMemoryTaskManager):
    def __init__(self, agent_wrapper):
        super().__init__()
        self.agent_wrapper = agent_wrapper
    
    async def on_send_task(self, request: SendTaskRequest) -> SendTaskResponse:
        params: TaskSendParams = request.params
        
        # Validate input
        if not self._has_text_input(params):
            return SendTaskResponse(
                id=request.id,
                error=InternalError(message="Only text input supported")
            )
        
        # Create task record
        await self.upsert_task(params)
        
        # Execute agent
        try:
            result = self.agent_wrapper.invoke(
                query=self._extract_text(params),
                session_id=params.sessionId
            )
        except Exception as e:
            status = TaskStatus(
                state=TaskState.FAILED,
                message=Message(role='agent', parts=[TextPart(text=str(e))])
            )
            await self.update_store(params.id, status, None)
            return SendTaskResponse(id=request.id, error=...)
        
        # Store result
        status = TaskStatus(
            state=TaskState.COMPLETED,
            message=Message(role='agent', parts=[TextPart(text=result)])
        )
        task = await self.update_store(params.id, status, None)
        return SendTaskResponse(id=request.id, result=task)
    
    async def on_send_task_subscribe(
        self, request: SendTaskStreamingRequest
    ) -> AsyncIterable[SendTaskStreamingResponse]:
        # Similar but use dequeue_events_for_sse for streaming
        ...
```

--------------------------------

### ADK-Native Orchestrator Workflow

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/05-orchestrators.md

Illustrates the flow of a complex multi-agent task using the ADK-Native orchestrator, involving delegation to tools and agents, followed by aggregation.

```text
User Request
    ↓
adk_orchestrator (LlmAgent)
    ├→ [Decision: This needs research + LinkedIn lookup]
    ├→ Delegate to deep_research_tool
    │   └→ Returns: Research report
    ├→ Delegate to scrape_profile_agent (LinkedIn)
    │   └→ Returns: CEO profile
    ├→ Aggregate and synthesize
    └→ Return final brief to user
```

--------------------------------

### Build and Run Commit ADK Agent Docker Container

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Commands to build the Docker image and run the Commit ADK agent container. It demonstrates how to pass necessary API keys as environment variables and map the container's port to the host.

```bash
docker build -t commit-adk-agent .

docker run -e GOOGLE_API_KEY=xxx \
           -e NOTION_API_KEY=yyy \
           -e PROXYCURL_API_KEY=zzz \
           -p 10000:10000 \
           commit-adk-agent
```

--------------------------------

### Dockerfile for Commit ADK Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Defines the Docker image for the Commit ADK agent. Includes installing dependencies, copying application code, and setting environment variables for API keys. Exposes port 10000 for the agent's service.

```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

ENV GOOGLE_API_KEY=${GOOGLE_API_KEY}
ENV NOTION_API_KEY=${NOTION_API_KEY}
ENV PROXYCURL_API_KEY=${PROXYCURL_API_KEY}

EXPOSE 10000

CMD ["python", "-m", "agents.python_developer"]
```

--------------------------------

### Write a Python Script with Developer Agent

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/08-quick-start-examples.md

Use the Python Developer Agent to generate a script that creates a list of numbers, filters even numbers, calculates their sum, and prints the result. Ensure the A2AClient is configured correctly.

```python
import asyncio
from common.client import A2AClient
from common.types import Message, TextPart

async def write_script():
    client = A2AClient(url="http://localhost:10000/")
    
    response = await client.send_task({
        "id": "code-script",
        "message": Message(
            role='user',
            parts=[TextPart(text="""
                Write a Python script that:
                1. Creates a list of numbers 1-100
                2. Filters even numbers
                3. Calculates their sum
                4. Prints the result
            """)]
        ).model_dump(),
    })
    
    print(response.result.status.message.parts[0].text)

asyncio.run(write_script())
```

--------------------------------

### Run Individual Python Agents

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Launch specific agents as independent A2A servers. Each agent listens on a predefined port.

```bash
# Python Developer (Port 10000)
python -m agents.python_developer

# LinkedIn (Port 10001)
python -m agents.linkedin

# Google Calendar (Port 10002)
python -m agents.google_calendar

# Deep Research (Port 10003)
python -m agents.deep_research

# Notion (Port 10004)
python -m agents.notion

# Browser (Port 10005)
python -m agents.browser
```

--------------------------------

### Enable Agent Streaming Capability

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Configure agent capabilities to enable streaming responses.

```python
capabilities=AgentCapabilities(streaming=True)
```

--------------------------------

### Task with Webhook Callback Workflow

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Shows how an agent can send task updates to a specified webhook URL instead of directly to the client.

```text
Client → Agent: POST / {tasks/send: "task-3"}
Agent → Client: Response with Task(status: working)
Agent → Webhook: POST /webhook {TaskStatusUpdateEvent}
Agent → Webhook: POST /webhook {TaskArtifactUpdateEvent}
Agent → Webhook: POST /webhook {TaskStatusUpdateEvent(final: true)}
```

--------------------------------

### Configure Vertex AI Code Executor

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Sets up the Vertex AI Code Executor by providing the resource name for subsequent runs after the extension has been created.

```python
code_executor=VertexAiCodeExecutor(
    resource_name="projects/YOUR_PROJECT/locations/us-central1/extensions/YOUR_EXTENSION_ID",
    ...
)
```

--------------------------------

### Required Google APIs Environment Variables

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Set either GOOGLE_API_KEY for Gemini or GOOGLE_CLOUD_PROJECT for Application Default Credentials.

```env
# Choice 1: Use Google AI Studio API Key (for Gemini)
GOOGLE_API_KEY=<API_KEY_FROM_AISTUDIO>

# Choice 2: Use Google Cloud Platform with Application Default Credentials
# (after: gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/calendar)
# (requires GOOGLE_CLOUD_PROJECT to be set)
GOOGLE_CLOUD_PROJECT=<YOUR_GCP_PROJECT_ID>
```

--------------------------------

### Configure Notion API Key

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Set the NOTION_API_KEY environment variable for the Notion Agent. Obtain the key from your Notion integration settings.

```env
NOTION_API_KEY="your_notion_api_key"
```

--------------------------------

### Per-Agent Environment File Locations

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Agents can load configurations from their specific local .env files, which override root .env settings for that agent.

```text
agents/python_developer/.env
agents/linkedin/.env
agents/notion/.env
agents/google_calendar/.env
```

--------------------------------

### Configure Agent Tools

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Customize tool parameters in `tools.py` and update the `tools` list in `agent.py` to include or modify external tools for an agent.

```python
tools=[
    custom_tool_1,
    custom_tool_2,
]
```

--------------------------------

### Streaming Task with Status Updates Workflow

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/07-protocol-reference.md

Illustrates a workflow where the client subscribes to a task and receives a stream of status and artifact updates.

```text
Client → Agent: POST / {tasks/sendSubscribe: "task-2"}
Agent → Client: SSE Stream:
                 - TaskStatusUpdateEvent(state: working)
                 - TaskArtifactUpdateEvent(artifact: ...)
                 - TaskStatusUpdateEvent(state: completed, final: true)
```

--------------------------------

### Set Google API Key Environment Variable

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/06-configuration-and-setup.md

Set the GOOGLE_API_KEY environment variable for authentication. Alternatively, use `gcloud auth application-default login` for application default credentials.

```bash
export GOOGLE_API_KEY=your_key
# or
gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
```

--------------------------------

### Register Agent Card Method

Source: https://github.com/commitgcp/commit-adk/blob/main/_autodocs/05-orchestrators.md

Dynamically registers a new agent's card at runtime. This allows for adding agents to the orchestrator after its initial creation.

```python
def register_agent_card(self, card: AgentCard)
```

--------------------------------

### Clone the Commit ADK Repository

Source: https://github.com/commitgcp/commit-adk/blob/main/README.md

Clone the official repository to your local machine and navigate into the project directory.

```bash
git clone https://github.com/commitgcp/commit-adk.git
cd commit-adk
```