|
| 1 | +# ADK Project Overview and Architecture |
| 2 | + |
| 3 | +Google Agent Development Kit (ADK) for Python |
| 4 | + |
| 5 | +## Core Philosophy & Architecture |
| 6 | + |
| 7 | +- Code-First: Everything is defined in Python code for versioning, testing, and IDE support. Avoid GUI-based logic. |
| 8 | + |
| 9 | +- Modularity & Composition: We build complex multi-agent systems by composing multiple, smaller, specialized agents. |
| 10 | + |
| 11 | +- Deployment-Agnostic: The agent's core logic is separate from its deployment environment. The same agent.py can be run locally for testing, served via an API, or deployed to the cloud. |
| 12 | + |
| 13 | +## Foundational Abstractions (Our Vocabulary) |
| 14 | + |
| 15 | +- Agent: The blueprint. It defines an agent's identity, instructions, and tools. It's a declarative configuration object. |
| 16 | + |
| 17 | +- Tool: A capability. A Python function an agent can call to interact with the world (e.g., search, API call). |
| 18 | + |
| 19 | +- Runner: The engine. It orchestrates the "Reason-Act" loop, manages LLM calls, and executes tools. |
| 20 | + |
| 21 | +- Session: The conversation state. It holds the history for a single, continuous dialogue. |
| 22 | + |
| 23 | +- Memory: Long-term recall across different sessions. |
| 24 | + |
| 25 | +- Artifact Service: Manages non-textual data like files. |
| 26 | + |
| 27 | +## Canonical Project Structure |
| 28 | + |
| 29 | +Adhere to this structure for compatibility with ADK tooling. |
| 30 | + |
| 31 | +my_adk_project/ \ |
| 32 | +└── src/ \ |
| 33 | + └── my_app/ \ |
| 34 | + ├── agents/ \ |
| 35 | + │ ├── my_agent/ \ |
| 36 | + │ │ ├── __init__.py # Must contain: from. import agent \ |
| 37 | + │ │ └── agent.py # Must contain: root_agent = Agent(...) \ |
| 38 | + │ └── another_agent/ \ |
| 39 | + │ ├── __init__.py \ |
| 40 | + │ └── agent.py\ |
| 41 | + |
| 42 | +agent.py: Must define the agent and assign it to a variable named root_agent. This is how ADK's tools find it. |
| 43 | + |
| 44 | +__init__.py: In each agent directory, it must contain from. import agent to make the agent discoverable. |
| 45 | + |
| 46 | +## Local Development & Debugging |
| 47 | + |
| 48 | +Interactive UI (adk web): This is our primary debugging tool. It's a decoupled system: |
| 49 | + |
| 50 | +Backend: A FastAPI server started with adk api_server. |
| 51 | + |
| 52 | +Frontend: An Angular app that connects to the backend. |
| 53 | + |
| 54 | +Use the "Events" tab to inspect the full execution trace (prompts, tool calls, responses). |
| 55 | + |
| 56 | +CLI (adk run): For quick, stateless functional checks in the terminal. |
| 57 | + |
| 58 | +Programmatic (pytest): For writing automated unit and integration tests. |
| 59 | + |
| 60 | +## The API Layer (FastAPI) |
| 61 | + |
| 62 | +We expose agents as production APIs using FastAPI. |
| 63 | + |
| 64 | +- get_fast_api_app: This is the key helper function from google.adk.cli.fast_api that creates a FastAPI app from our agent directory. |
| 65 | + |
| 66 | +- Standard Endpoints: The generated app includes standard routes like /list-apps and /run_sse for streaming responses. The wire format is camelCase. |
| 67 | + |
| 68 | +- Custom Endpoints: We can add our own routes (e.g., /health) to the app object returned by the helper. |
| 69 | + |
| 70 | +Python |
| 71 | + |
| 72 | +from google.adk.cli.fast_api import get_fast_api_app |
| 73 | +app = get_fast_api_app(agent_dir="./agents") |
| 74 | + |
| 75 | +@app.get("/health") |
| 76 | +async def health_check(): |
| 77 | + return {"status": "ok"} |
| 78 | + |
| 79 | + |
| 80 | +## Deployment to Production |
| 81 | + |
| 82 | +The adk cli provides the "adk deploy" command to deploy to Google Vertex Agent Engine, Google CloudRun, Google GKE. |
| 83 | + |
| 84 | +## Testing & Evaluation Strategy |
| 85 | + |
| 86 | +Testing is layered, like a pyramid. |
| 87 | + |
| 88 | +### Layer 1: Unit Tests (Base) |
| 89 | + |
| 90 | +What: Test individual Tool functions in isolation. |
| 91 | + |
| 92 | +How: Use pytest in tests/test_tools.py. Verify deterministic logic. |
| 93 | + |
| 94 | +### Layer 2: Integration Tests (Middle) |
| 95 | + |
| 96 | +What: Test the agent's internal logic and interaction with tools. |
| 97 | + |
| 98 | +How: Use pytest in tests/test_agent.py, often with mocked LLMs or services. |
| 99 | + |
| 100 | +### Layer 3: Evaluation Tests (Top) |
| 101 | + |
| 102 | +What: Assess end-to-end performance with a live LLM. This is about quality, not just pass/fail. |
| 103 | + |
| 104 | +How: Use the ADK Evaluation Framework. |
| 105 | + |
| 106 | +Test Cases: Create JSON files with input and a reference (expected tool calls and final response). |
| 107 | + |
| 108 | +Metrics: tool_trajectory_avg_score (does it use tools correctly?) and response_match_score (is the final answer good?). |
| 109 | + |
| 110 | +Run via: adk web (UI), pytest (for CI/CD), or adk eval (CLI). |
| 111 | + |
0 commit comments