# vishal-bulbule/adk-python architecture

> Architecture diagram of the GitHub repository vishal-bulbule/adk-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishal-bulbule/adk-python
- Repository: https://github.com/vishal-bulbule/adk-python

## Overview

ADK is a Python framework for defining, orchestrating, evaluating, and deploying AI agents. The primary workflow starts with a developer defining agents and optional workflows, then running them locally or through the web interface; agents use models and tools, while session/event state supports ongoing interactions. The README documents additional branches for evaluation, agent-to-agent tasks, configuration, and deployment. Source excerpts are limited, so unverified runtime connections are omitted rather than inferred.

Main entry points: [`src/google/adk/workflow`](https://github.com/vishal-bulbule/adk-python/tree/main/src/google/adk/workflow) (Workflow runtime), [`src/google/adk/agents/llm_agent.py`](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/llm_agent.py) (LLM agent), [`src/google/adk/sessions/session.py`](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/sessions/session.py) (Session history), [`src/google/adk/agents/base_agent.py`](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/base_agent.py) (Agent definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Agent authoring"]
  node_agent_api["Agent definitions<br/>[base_agent.py]"]
  node_agent_config["Agent Config<br/>[agent_config.py]"]
end

subgraph group_runtime["Workflow runtime"]
  node_workflow["Workflow runtime"]
  node_llm_agent["LLM agent<br/>[llm_agent.py]"]
  node_llm_request["Model requests<br/>[llm_request.py]"]
  node_llm_response["Model responses<br/>[llm_response.py]"]
end

subgraph group_capabilities["Tools and delegation"]
  node_tool_runtime["Tool execution<br/>[base_tool.py]"]
  node_a2a_tasks["Agent task API"]
end

subgraph group_state["Interaction state"]
  node_session["Session history<br/>[session.py]"]
  node_session_service["Session services"]
  node_event["Interaction events<br/>[event.py]"]
  node_state["Scoped state<br/>[state.py]"]
  node_artifact_service["Artifact services"]
end

subgraph group_operations["Development operations"]
  node_cli["CLI and web<br/>[cli.py]"]
  node_evaluation["Agent evaluation<br/>[agent_evaluator.py]"]
  node_deployment["Deployment targets"]
end

node_developer(("Developer"))

node_developer -->|"defines agents"| node_agent_api
node_developer -->|"composes workflow"| node_workflow
node_agent_api -->|"orchestrates agents"| node_workflow
node_developer -->|"configures agents"| node_agent_config
node_developer -->|"runs locally"| node_cli
node_cli -->|"deploys agents"| node_deployment
node_developer -->|"evaluates agents"| node_evaluation
node_llm_agent -.->|"requests model"| node_llm_request
node_llm_request -.->|"receives response"| node_llm_response
node_llm_agent -->|"invokes tools"| node_tool_runtime
node_workflow -->|"supports task agents"| node_a2a_tasks
node_session_service -.->|"stores sessions"| node_session
node_session -->|"records events"| node_event
node_session -->|"holds state"| node_state
node_workflow -.->|"uses session service"| node_session_service
node_llm_agent -.->|"uses artifacts"| node_artifact_service

click node_agent_api "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/base_agent.py"
click node_agent_config "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/agent_config.py"
click node_workflow "https://github.com/vishal-bulbule/adk-python/tree/main/src/google/adk/workflow"
click node_llm_agent "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/llm_agent.py"
click node_llm_request "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/models/llm_request.py"
click node_llm_response "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/models/llm_response.py"
click node_tool_runtime "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/tools/base_tool.py"
click node_a2a_tasks "https://github.com/vishal-bulbule/adk-python/tree/main/src/google/adk/a2a"
click node_session "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/sessions/session.py"
click node_session_service "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/sessions/base_session_service.py"
click node_event "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/events/event.py"
click node_state "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/sessions/state.py"
click node_cli "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/cli/cli.py"
click node_evaluation "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/evaluation/agent_evaluator.py"
click node_deployment "https://github.com/vishal-bulbule/adk-python/tree/main/src/google/adk/cli/deployers"
click node_artifact_service "https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/artifacts/base_artifact_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_api,node_agent_config toneBlue
class node_workflow,node_llm_agent,node_llm_request,node_llm_response toneAmber
class node_tool_runtime,node_a2a_tasks toneMint
class node_session,node_session_service,node_event,node_state,node_artifact_service toneRose
class node_cli,node_evaluation,node_deployment,node_developer toneIndigo
```

## Components

### Agent authoring

- [Agent definitions](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/base_agent.py): `src/google/adk/agents/base_agent.py`
- [Agent Config](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/agent_config.py): `src/google/adk/agents/agent_config.py`

### Workflow runtime

- [Workflow runtime](https://github.com/vishal-bulbule/adk-python/tree/main/src/google/adk/workflow): `src/google/adk/workflow`
- [LLM agent](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/agents/llm_agent.py): `src/google/adk/agents/llm_agent.py`
- [Model requests](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/models/llm_request.py): `src/google/adk/models/llm_request.py`
- [Model responses](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/models/llm_response.py): `src/google/adk/models/llm_response.py`

### Tools and delegation

- [Tool execution](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/tools/base_tool.py): `src/google/adk/tools/base_tool.py`
- [Agent task API](https://github.com/vishal-bulbule/adk-python/tree/main/src/google/adk/a2a): `src/google/adk/a2a`

### Interaction state

- [Session history](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/sessions/session.py): `src/google/adk/sessions/session.py`
- [Session services](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/sessions/base_session_service.py): `src/google/adk/sessions/base_session_service.py`
- [Interaction events](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/events/event.py): `src/google/adk/events/event.py`
- [Scoped state](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/sessions/state.py): `src/google/adk/sessions/state.py`
- [Artifact services](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/artifacts/base_artifact_service.py): `src/google/adk/artifacts/base_artifact_service.py`

### Development operations

- [CLI and web](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/cli/cli.py): `src/google/adk/cli/cli.py`
- [Agent evaluation](https://github.com/vishal-bulbule/adk-python/blob/main/src/google/adk/evaluation/agent_evaluator.py): `src/google/adk/evaluation/agent_evaluator.py`
- [Deployment targets](https://github.com/vishal-bulbule/adk-python/tree/main/src/google/adk/cli/deployers): `src/google/adk/cli/deployers`

### Other components

- **Developer**

## Connections

- Developer → Agent definitions: defines agents (evidence: `README.md`)
- Developer → Workflow runtime: composes workflow (evidence: `README.md`)
- Agent definitions → Workflow runtime: orchestrates agents (evidence: `README.md`)
- Developer → Agent Config: configures agents (evidence: `README.md`)
- Developer → CLI and web: runs locally (evidence: `README.md`)
- CLI and web → Deployment targets: deploys agents (evidence: `README.md`)
- Developer → Agent evaluation: evaluates agents (evidence: `README.md`)
- LLM agent → Model requests: requests model
- Model requests → Model responses: receives response
- LLM agent → Tool execution: invokes tools (evidence: `README.md`)
- Workflow runtime → Agent task API: supports task agents (evidence: `README.md`)
- Session services → Session history: stores sessions (evidence: `src/google/adk/sessions/base_session_service.py`)
- Session history → Interaction events: records events (evidence: `src/google/adk/sessions/session.py`)
- Session history → Scoped state: holds state (evidence: `src/google/adk/sessions/session.py`)
- Workflow runtime → Session services: uses session service
- LLM agent → Artifact services: uses artifacts