ADK agents are designed to be written by humans and AI. Connect your AI-powered development tools to our ADK coding resources and generate robust, capable agents in seconds.
We think one of the best ways to learn is by building, so we've created guides that help you get your development environment set up and run an ADK agent in minutes.
diff --git a/docs/_includes/homepage/_community.md b/docs/_includes/homepage/_community.md
new file mode 100644
index 0000000000..edd8a581b2
--- /dev/null
+++ b/docs/_includes/homepage/_community.md
@@ -0,0 +1,26 @@
+
+
+
Developer Community
+
Build alongside a growing community of developers engineering the next generation of production-ready AI agents. Whether you want to troubleshoot a graph workflow, share a custom Agent Skill, or shape the future of the framework, we want you involved.
diff --git a/docs/_includes/homepage/_ecosystem.md b/docs/_includes/homepage/_ecosystem.md
new file mode 100644
index 0000000000..e5155f6701
--- /dev/null
+++ b/docs/_includes/homepage/_ecosystem.md
@@ -0,0 +1,14 @@
+
+
+
+ Ecosystem
+
Open ecosystem. Connect everything.
+
ADK's open integration partners connect your agents with existing apps, a wide range of AI models, and extend agent capabilities to access data, add resilience, and evaluate performance.
diff --git a/docs/_includes/homepage/_eval.md b/docs/_includes/homepage/_eval.md
new file mode 100644
index 0000000000..55dcb76c4f
--- /dev/null
+++ b/docs/_includes/homepage/_eval.md
@@ -0,0 +1,14 @@
+
+
+
+ Evaluation
+
Go beyond vibes. Evaluate everything.
+
Engage ADK's visual debugging, open evaluation framework, and partner tools to test your entire agent execution trajectory. Simulate user interactions, build custom performance metrics, and optimize agents against your evaluation results.
diff --git a/docs/_includes/homepage/_faq.md b/docs/_includes/homepage/_faq.md
new file mode 100644
index 0000000000..72538916c9
--- /dev/null
+++ b/docs/_includes/homepage/_faq.md
@@ -0,0 +1,39 @@
+
+
+
Frequently Asked Questions
+
Still have questions about ADK? Here are some answers:
+
+
+
+
+ Can I vibe code agents with ADK?
+
Yes! ADK is designed to be written by both humans and AI. Connect your favorite coding assistant to our ADK developer Skills and AI-aware developer resources, and generate agents in seconds. Find out more about AI-powered coding of agents in our Coding with AI guide.
+
+
+
+ What AI models can I use with ADK?
+
ADK can work with almost any generative AI model. The framework provides easy access to Gemini as well as other leading models, and we provide adapters that let you connect with many other models and model providers, including locally running models. For enterprises, ADK can connect to models on hosted services, including Google Cloud which provides a wide range of models and lets you closely manage performance, reliability, security, access, safety, and costs.
+
+
+
+ What makes ADK different?
+
With ADK, we are focused on building an open development framework that lets you build professional, production grade agents, without requiring a pile of code to get started. Our goal is to get you building agents quickly, and let you add functionality and complexity as you need it. ADK provides a basic structure for agents that is easy to build, and that structure is designed with the flexibility to let you extend, expand, and build complex, robust, useful agentic systems. We've put a lot of effort into providing you with development tools for interacting with agents you build, and providing ways to use AI-powered tools for building ADK agents. We are also quite proud of our approach to agent context management and how we manage context to keep it efficient, and also let you tune context management to your needs. We could go on, and if you are interested, you can find more details in our developer docs.
+
+
+
+ How does ADK handle context management?
+
Unlike tools that simply paste strings together until the context window overflows, ADK manages your context. We treat context like source code—sessions, memory, tool outputs, and artifacts are assembled into a structured view where every token earns its place. ADK automatically filters irrelevant events, summarizes older conversational turns, lazy-loads artifacts, and tracks token usage. This approach keeps your agents fast, efficient, and reliable by default, while giving you the controls to fully customize how context is managed for complex tasks.
+
+
+
+ How does ADK deploy to production?
+
ADK is built for deploy anywhere flexibility. You can containerize and run ADK on your own infrastructure, or take advantage of our native, one-command deployment to Google Cloud. When deploying to Google Cloud via Agent Runtime (Agent Platform), Cloud Run, or GKE, your agents instantly inherit managed infrastructure, built-in authentication, Cloud Trace observability, and enterprise-grade security—all without requiring you to change a single line of your agent code. Develop locally, scale globally.
+
+
+
+ When should I use an agent framework to work with generative AI?
+
AI chat conversations can accomplish many tasks, but when you need to accomplish complex, multi-step processes, an agent framework lets you create a managed, repeatable task structure that can run hands-off with minimal human input. Agent frameworks like ADK can automatically initiate tasks, make multiple iterative AI model requests, manage context, handle tool calls, record data, run parallel jobs, handle failures, and resume tasks if they get stopped.
+
+
+
+
diff --git a/docs/_includes/homepage/_framework.md b/docs/_includes/homepage/_framework.md
new file mode 100644
index 0000000000..7ad326d96a
--- /dev/null
+++ b/docs/_includes/homepage/_framework.md
@@ -0,0 +1,14 @@
+
+
+
+ Framework
+
Powerful simplicity. Built for scale.
+
Start building ADK agents with prompts and tool calls, then grow to multi-agent orchestration, graph-based workflows, performance evaluation, and deployment to world class enterprise services for scalability, reliability, and throughput.
diff --git a/docs/_includes/homepage/_hero.md b/docs/_includes/homepage/_hero.md
new file mode 100644
index 0000000000..2d62c84db2
--- /dev/null
+++ b/docs/_includes/homepage/_hero.md
@@ -0,0 +1,91 @@
+
+
+
+
Build production agents, not prototypes.
+
ADK is the open-source agent development framework that lets you build, debug, and deploy reliable AI agents at enterprise scale. Available in Python, TypeScript, Go, and Java.
diff --git a/docs/a2a/a2a-extension.md b/docs/a2a/a2a-extension.md
new file mode 100644
index 0000000000..6e6170f596
--- /dev/null
+++ b/docs/a2a/a2a-extension.md
@@ -0,0 +1,61 @@
+# A2A extension for improved reliability
+
+
+ Supported in ADKPython 1.27.0
+
+
+ADK provides an extension for Agent2Agent (A2A) support to improved message and data handling as part of
+an updated [A2aAgentExecutor](https://github.com/google/adk-python/blob/main/src/google/adk/a2a/executor/a2a_agent_executor_impl.py)
+class. The updated version includes updates to architectural changes to the core agent execution logic
+and extensions for A2A to improve data handling, while also providing backward compatibility with
+existing A2A agents.
+
+Activating the A2A extension option instructs the server to use the updated agent executor implementation.
+While this update offers several general advantages, it primarily resolves critical limitations found in
+the legacy A2A-ADK implementation when both A2A and ADK operate in streaming mode. The new implementation
+addresses the following issues:
+
+- **Message duplication:** Prevents user messages from being duplicated in the task history.
+- **Output misclassification:** Stops remote agent ADK outputs from being incorrectly converted into
+ event thoughts.
+- **Sub-agent data loss:** Ensures ADK outputs from remote agents are reliably preserved, eliminating
+ data loss when multiple agents are nested within the remote agent's sub-agent tree.
+
+## Client-side extension activation
+
+Clients indicate their desire to use this extension by specifying it via the transport-defined [A2A extension](https://a2a-protocol.org/latest/topics/extensions/) activation mechanism.
+For JSON-RPC and HTTP transports, this is indicated via the X-A2A-Extensions HTTP header.
+For gRPC, this is indicated via the X-A2A-Extensions metadata value.
+
+To activate the extension, the client can instantiate the `RemoteA2aAgent` with `use_legacy=False`. This will add `https://google.github.io/adk-docs/a2a/a2a-extension/` among the requested extensions of the sent request.
+Activating this extension implies that the server will use the new agent executor implementation.
+
+```python
+from google.adk.agents import RemoteA2aAgent
+
+remote_agent = RemoteA2aAgent(
+ name="remote_agent",
+ url="http://localhost:8000/a2a/remote_agent",
+ use_legacy=False,
+)
+```
+
+The `A2aAgentExecutor` uses by default the new implementation, if the a2a extension is detected in the request.
+To opt-out the new agent executor implementation, the client can simply not send this extension (instantiating the `RemoteA2aAgent` with `use_legacy=True`) or the server's `A2aAgentExecutor` can be instantiated with `use_legacy=True`.
+
+## How it Works
+
+Upon receiving the request, the [A2aAgentExecutor](https://github.com/google/adk-python/blob/main/src/google/adk/a2a/executor/a2a_agent_executor.py) detects the extension. It understands that the client is requesting to use the new agent executor logic and routes the request to the new implementation accordingly. To confirm that the request was honored, it is then included in the "activated extensions" list within the response metadata sent back to the client, as well as in the metadata of the A2A Events.
+
+## Agent Card definition
+
+Agents advertise this extension capability in their AgentCard within the AgentCapabilities.extensions list.
+
+Example AgentExtension block:
+```json
+{
+ "uri": "https://google.github.io/adk-docs/a2a/a2a-extension/",
+ "description": "Ability to use the new agent executor implementation",
+ "required": false
+}
+```
diff --git a/docs/a2a/index.md b/docs/a2a/index.md
index 275c986b1f..dc2a96aedd 100644
--- a/docs/a2a/index.md
+++ b/docs/a2a/index.md
@@ -1,7 +1,7 @@
# ADK with Agent2Agent (A2A) Protocol
- Supported in ADKPythonGoExperimental
+ Supported in ADKPythonGoJavaExperimental
With Agent Development Kit (ADK), you can build complex multi-agent systems where different agents need to collaborate and interact using [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/)! This section provides a comprehensive guide to building powerful multi-agent systems where agents can communicate and collaborate securely and efficiently.
@@ -14,11 +14,14 @@ Navigate through the guides below to learn about ADK's A2A capabilities:
* **[A2A Quickstart (Exposing) for Python](./quickstart-exposing.md)**
* **[A2A Quickstart (Exposing) for Go](./quickstart-exposing-go.md)**
+ * **[A2A Quickstart (Exposing) for Java](./quickstart-exposing-java.md)**
These guides show you how to allow your agent to use another, remote agent using A2A protocol:
* **[A2A Quickstart (Consuming) for Python](./quickstart-consuming.md)**
+ * **[A2A Extension - V2 Implementation](./a2a-extension.md)**
* **[A2A Quickstart (Consuming) for Go](./quickstart-consuming-go.md)**
+ * **[A2A Quickstart (Consuming) for Java](./quickstart-consuming-java.md)**
[**Official Website for Agent2Agent (A2A) Protocol**](https://a2a-protocol.org/)
diff --git a/docs/a2a/intro.md b/docs/a2a/intro.md
index 4c2c30736f..c3d0788406 100644
--- a/docs/a2a/intro.md
+++ b/docs/a2a/intro.md
@@ -253,4 +253,4 @@ concerns and easy integration of specialized agents.
Now that you understand the "why" of A2A, let's dive into the "how."
- **Continue to the next guide:**
- [Quickstart: Exposing Your Agent](./quickstart-exposing.md)
+ Quickstart: Exposing Your Agent, [in Python](./quickstart-exposing.md), [in Go](./quickstart-exposing-go.md), [in Java](./quickstart-exposing-java.md)
diff --git a/docs/a2a/quickstart-consuming-go.md b/docs/a2a/quickstart-consuming-go.md
index 2ed1358dd1..2df2f79453 100644
--- a/docs/a2a/quickstart-consuming-go.md
+++ b/docs/a2a/quickstart-consuming-go.md
@@ -8,7 +8,7 @@ This quickstart covers the most common starting point for any developer: **"Ther
## Overview
-This sample demonstrates the **Agent-to-Agent (A2A)** architecture in the Agent Development Kit (ADK), showcasing how multiple agents can work together to handle complex tasks. The sample implements an agent that can roll dice and check if numbers are prime.
+This sample demonstrates the **Agent2Agent (A2A)** architecture in the Agent Development Kit (ADK), showcasing how multiple agents can work together to handle complex tasks. The sample implements an agent that can roll dice and check if numbers are prime.
```text
┌─────────────────┐ ┌──────────────────┐ ┌────────────────────┐
diff --git a/docs/a2a/quickstart-consuming-java.md b/docs/a2a/quickstart-consuming-java.md
new file mode 100644
index 0000000000..3259a23cdb
--- /dev/null
+++ b/docs/a2a/quickstart-consuming-java.md
@@ -0,0 +1,84 @@
+# Quickstart: Consuming a remote agent via A2A
+
+
+ Supported in ADKJavaExperimental
+
+
+This quickstart covers the most common starting point for any developer: **"There is a remote agent, how do I let my ADK agent use it via A2A?"**. This is crucial for building complex multi-agent systems where different agents need to collaborate and interact.
+
+## Overview
+
+This sample demonstrates the **Agent2Agent (A2A)** architecture in the Agent Development Kit (ADK) for Java, showcasing how multiple agents can work together to handle complex tasks.
+
+```text
+┌─────────────────┐ ┌─────────────────┐ ┌────────────────────────┐
+│ Root Agent │───▶│ Roll Agent │ │ Remote Prime Agent │
+│ (Local) │ │ (Local) │ │ (localhost:8001) │
+│ │───▶│ │◀───│ │
+└─────────────────┘ └─────────────────┘ └────────────────────────┘
+```
+
+The A2A Basic sample consists of:
+
+- **Root Agent** (`root_agent`): The main orchestrator that delegates tasks to specialized sub-agents
+- **Roll Agent** (`roll_agent`): A local sub-agent that handles dice rolling operations
+- **Prime Agent** (`prime_agent`): A remote A2A agent that checks if numbers are prime, this agent is running on a separate A2A server
+
+## Consuming Your Agent Using the ADK Java SDK
+
+In Java, rather than manually generating requests, ADK relies on the official A2A SDK `Client` wrapped precisely over a `RemoteA2AAgent` entity. Note that the Java SDK currently uses A2A Protocol 0.3.
+
+### 1. Getting the Sample Code { #getting-the-sample-code }
+
+The native sample matching this quickstart workflow in Java can be found in the `adk-java` source code under `contrib/samples/a2a_basic`.
+
+You can navigate to the [**`a2a_basic`** sample](https://github.com/google/adk-java/tree/main/contrib/samples/a2a_basic):
+
+```bash
+cd contrib/samples/a2a_basic
+```
+
+### 2. Start the Remote Prime Agent server { #start-the-remote-prime-agent-server }
+
+To show how your ADK agent can consume a remote agent via A2A, you'll first need a remote agent server running. While you can write your own custom A2A server in any language, ADK provides the `a2a_server` sample which starts a Quarkus service hosting the agent on `:9090`.
+
+```bash
+# In adk-java root, start the pre-configured Quarkus remote service on port 9090
+./mvnw -f contrib/samples/a2a_server/pom.xml quarkus:dev
+```
+
+Once running successfully, the agent will be accessible via HTTP endpoints locally.
+
+### 3. Look out for the required agent card of the remote agent { #look-out-for-the-required-agent-card-of-the-remote-agent }
+
+A2A Protocol requires that each agent have an agent card that describes what it does to other nodes over the network. In an A2A server, the agent card is generated dynamically on boot and hosted statically.
+
+For an ADK Java webservice, the agent card is generally accessible dynamically using the [`.well-known/agent-card.json`](http://localhost:9090/.well-known/agent-card.json) standard endpoint format relative to its base URL.
+
+### 4. Run the Main (Consuming) Agent { #run-the-main-consuming-agent }
+
+In another terminal, you can run the client agent:
+
+```bash
+./mvnw -f contrib/samples/a2a_basic/pom.xml exec:java -Dexec.args="http://localhost:9090"
+```
+
+#### How it works
+
+The main agent accesses the required A2A JSON-RPC transport wrapper to consume the remote agent (`prime_agent` in our example). As you can see below, it queries for the `AgentCard` from the target host and registers it locally inside an official A2A `Client`.
+
+```java title="A2aConsumerSnippet.java"
+--8<-- "examples/java/snippets/src/main/java/a2a/A2aConsumerSnippet.java:new-prime-agent"
+```
+
+You can then pass the remote agent instance naturally to your agent builder, simply acting as just another standard ADK sub-agent. The ADK takes over internally for all translation logic over the wire.
+
+```java title="A2aConsumerSnippet.java"
+--8<-- "examples/java/snippets/src/main/java/a2a/A2aConsumerSnippet.java:new-root-agent"
+```
+
+## Next Steps
+
+Now that you have created an agent that's using a remote agent via an A2A server, the next step is to learn how to expose your own Java agent.
+
+- [**A2A Quickstart (Exposing) for Java**](./quickstart-exposing-java.md): Learn how to expose your existing agent so that other agents can use it via the A2A Protocol.
diff --git a/docs/a2a/quickstart-consuming.md b/docs/a2a/quickstart-consuming.md
index 7e31016e13..5ebec89e00 100644
--- a/docs/a2a/quickstart-consuming.md
+++ b/docs/a2a/quickstart-consuming.md
@@ -156,11 +156,15 @@ prime_agent = RemoteA2aAgent(
agent_card=(
f"http://localhost:8001/a2a/check_prime_agent{AGENT_CARD_WELL_KNOWN_PATH}"
),
+ use_legacy=False,
)
<...code truncated>
```
+!!! note "Using the new A2A integration"
+ By setting `use_legacy=False`, the agent will use the new ADK-A2A integration, as it will send the [A2A extension](a2a-extension.md) to the remote agent.
+
Then, you can simply use the `RemoteA2aAgent` in your agent. In this case, `prime_agent` is used as one of the sub-agents in the `root_agent` below:
```python title="a2a_basic/agent.py"
@@ -168,7 +172,7 @@ from google.adk.agents.llm_agent import Agent
from google.genai import types
root_agent = Agent(
- model="gemini-2.0-flash",
+ model="gemini-flash-latest",
name="root_agent",
instruction="""
+
+from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH
+from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
+
+prime_agent = RemoteA2aAgent(
+ name="prime_agent",
+ description="Agent that handles checking if numbers are prime.",
+ agent_card=(
+ f"http://localhost:8001/a2a/check_prime_agent{AGENT_CARD_WELL_KNOWN_PATH}"
+ ),
+ use_legacy=False,
+ config=A2aRemoteAgentConfig(
+ a2a_message_converter=my_a2a_message_converter,
+ request_interceptors=[my_request_interceptor],
+ ),
+)
+
+<...code truncated>
+```
+
+
## Example Interactions
Once both your main and remote agents are running, you can interact with the root agent to see how it calls the remote agent via A2A:
diff --git a/docs/a2a/quickstart-exposing-java.md b/docs/a2a/quickstart-exposing-java.md
new file mode 100644
index 0000000000..5dfb459af7
--- /dev/null
+++ b/docs/a2a/quickstart-exposing-java.md
@@ -0,0 +1,86 @@
+# Quickstart: Exposing a remote agent via A2A
+
+
+ Supported in ADKJavaExperimental
+
+
+This quickstart covers the most common starting point for any developer: **"I have an agent. How do I expose it so that other agents can use my agent via A2A?"**. This is crucial for building complex multi-agent systems where different agents need to collaborate and interact.
+
+## Overview
+
+This sample demonstrates how you can expose an ADK agent using Quarkus so that it can be then consumed by another agent using the A2A Protocol.
+
+In Java, you build an A2A server natively by relying on the ADK A2A extension. This uses the Quarkus framework, meaning you just configure your agent directly within your standard Quarkus `@ApplicationScoped` bindings.
+
+```text
+┌─────────────────┐ ┌───────────────────────────────┐
+│ Root Agent │ A2A Protocol │ A2A-Exposed Check Prime Agent │
+│ │────────────────────────────▶│ (localhost:9090) │
+└─────────────────┘ └───────────────────────────────┘
+```
+
+## Exposing the Remote Agent with Quarkus
+
+Using Quarkus, you map your agent into an A2A execution endpoint without manually wrangling incoming HTTP JSON-RPC payloads or sessions.
+
+### 1. Getting the Sample Code { #getting-the-sample-code }
+
+The fastest way to get started is by checking the standalone Quarkus app inside the `contrib/samples/a2a_server` folder within the [**`adk-java`** repo](https://github.com/google/adk-java).
+
+```bash
+cd contrib/samples/a2a_server
+```
+
+### 2. How it works
+
+The core runtime uses a provided `AgentExecutor` which requires you to build a CDI `@Produces` bean configuring your native `BaseAgent`. The Quarkus A2A extension discovers this and wires the endpoints automatically.
+
+```java title="A2aExposingSnippet.java"
+--8<-- "examples/java/snippets/src/main/java/a2a/A2aExposingSnippet.java:a2a-launcher"
+```
+
+The app handles incoming JSON-RPC calls over HTTP mounted on `/a2a/remote/v1/message:send` automatically forwarding parts, history, and contexts directly into your `BaseAgent` flow.
+
+### 3. Start the Remote A2A Agent server { #start-the-remote-a2a-agent-server }
+
+Within the native ADK structure, you can run the Quarkus dev mode task:
+
+```bash
+./mvnw -f contrib/samples/a2a_server/pom.xml quarkus:dev
+```
+
+Once executed, Quarkus automatically hosts your A2A compliant REST paths. A manual `curl` allows you to immediately smoke test the payload using native A2A specifications:
+
+```bash
+curl -X POST http://localhost:9090 \
+ -H "Content-Type: application/json" \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": "cli-check",
+ "method": "message/send",
+ "params": {
+ "message": {
+ "kind": "message",
+ "contextId": "cli-demo-context",
+ "messageId": "cli-check-id",
+ "role": "user",
+ "parts": [
+ { "kind": "text", "text": "Is 3 prime?" }
+ ]
+ }
+ }
+ }'
+```
+
+### 4. Check that your remote agent is running { #check-that-your-remote-agent-is-running }
+
+A proper agent card is exposed over a standard path representing your instance automatically:
+[http://localhost:9090/.well-known/agent-card.json](http://localhost:9090/.well-known/agent-card.json)
+
+You should be able to see the name dynamically mirrored from your agent configuration inside the response JSON.
+
+## Next Steps
+
+Now that you have exposed your agent via A2A, the next step is to learn how to consume it from another agent orchestrator natively.
+
+- [**A2A Quickstart (Consuming) for Java**](./quickstart-consuming-java.md): Learn how your agent orchestrator wrapper connects downstream to exposed services.
diff --git a/docs/a2a/quickstart-exposing.md b/docs/a2a/quickstart-exposing.md
index 7e8e79ee16..359bd4f427 100644
--- a/docs/a2a/quickstart-exposing.md
+++ b/docs/a2a/quickstart-exposing.md
@@ -49,7 +49,7 @@ You can take an existing agent built using ADK and make it A2A-compatible by sim
```python
# Your agent code here
root_agent = Agent(
- model='gemini-2.0-flash',
+ model='gemini-flash-latest',
name='hello_world_agent',
<...your agent code...>
@@ -82,9 +82,9 @@ my_agent_card = AgentCard(
version="1.0.0",
capabilities={},
skills=[],
- defaultInputModes=["text/plain"],
- defaultOutputModes=["text/plain"],
- supportsAuthenticatedExtendedCard=False,
+ default_input_modes=["text/plain"],
+ default_output_modes=["text/plain"],
+ supports_authenticated_extended_card=False,
)
a2a_app = to_a2a(root_agent, port=8001, agent_card=my_agent_card)
```
@@ -97,6 +97,15 @@ from google.adk.a2a.utils.agent_to_a2a import to_a2a
a2a_app = to_a2a(root_agent, port=8001, agent_card="/path/to/your/agent-card.json")
```
+### Under the hood: to_a2a() method
+
+When you call `to_a2a()`, the ADK automatically handles several setup steps to expose your agent:
+
+* **`A2aAgentExecutor` setup:** An `A2aAgentExecutor` is initialized to act as the bridge between the A2A protocol and your ADK agent. If you don't provide a custom `Runner`, it automatically creates a default one backed by in-memory services (for artifacts, sessions, memory, and credentials).
+* **State Management:** It creates an `InMemoryTaskStore` to track A2A tasks and an `InMemoryPushNotificationConfigStore` for handling push notifications.
+* **Request Handling:** A `DefaultRequestHandler` is created to route incoming A2A HTTP requests to the `A2aAgentExecutor` and the state stores.
+* **Starlette App & Agent Card:** It creates a Starlette application. During the application's startup phase, it either loads your provided Agent Card or automatically builds one from your agent's configuration using an `AgentCardBuilder`. It then mounts all the necessary A2A API routes.
+
Now let's dive into the sample code.
### 1. Getting the Sample Code { #getting-the-sample-code }
@@ -213,6 +222,43 @@ Bot: I rolled an 8 for you.
Bot: 8 is not a prime number.
```
+## Advanced Configuration: Custom Converters and Interceptors
+
+In scenarios where you want more granular control than what `to_a2a()` provides, you may instantiate and pass an [`A2aAgentExecutorConfig`](https://github.com/google/adk-python/blob/main/src/google/adk/a2a/executor/config.py) directly to the `A2aAgentExecutor`. This allows you to override default data converters and inject execution middleware.
+
+### Converters
+
+Converters handle the bidirectional translation between A2A protocol payloads and ADK's native `Event` or `Part` objects. You can provide your own mapping functions for the following hooks:
+
+* **`a2a_part_converter`**: Converts A2A Message Parts into ADK `Part` objects.
+* **`gen_ai_part_converter`**: Converts native ADK `Part` objects into A2A Message Parts.
+* **`request_converter`**: Converts an incoming A2A request into an ADK `RunRequest`.
+* **`event_converter`**: *(Legacy)* Converts an ADK Event into an A2A Event, used by the legacy executor implementation.
+* **`adk_event_converter`**: *(New)* Converts an ADK Event into an A2A Event, used by the new, updated executor implementation.
+
+### Execute Interceptors
+
+You can inject a list of `execute_interceptors` to add middleware logic to the `A2aAgentExecutor` payload processing:
+
+* **`before_agent`**: Executed before the agent starts processing the request. It allows you to inspect or modify the incoming `RequestContext`.
+* **`after_event`**: Executed *after* an ADK event is converted to an A2A event. Allows you to mutate the outgoing event before it is enqueued, or return `None` to filter out and drop the event entirely.
+* **`after_agent`**: Executed after the agent finishes and the final event is prepared. Use this to inspect or modify the terminal status event (e.g., `completed` or `failed`) before it is sent.
+
+## Agent Executor V2
+
+The new version of the [agent executor](https://github.com/google/adk-python/blob/main/src/google/adk/a2a/executor/a2a_agent_executor_impl.py) is typically enabled when a client sends the required [A2A extension](a2a-extension.md).
+
+However, you can also bypass the extension and force the server to use the new executor version by setting the `force_new_version=True` flag when instantiating the `A2aAgentExecutor`. This allows you to use the new executor logic without needing to modify existing clients to send the extension.
+
+```python
+from google.adk.a2a.executor import A2aAgentExecutor
+
+executor = A2aAgentExecutor(
+ ...,
+ force_new_version=True
+ )
+```
+
## Next Steps
Now that you have created an agent that's exposing a remote agent via an A2A server, the next step is to learn how to consume it from another agent.
diff --git a/docs/agents/config.md b/docs/agents/config.md
index 28b20846aa..38275801b3 100644
--- a/docs/agents/config.md
+++ b/docs/agents/config.md
@@ -1,7 +1,7 @@
# Build agents with Agent Config
- Supported in ADKPython v1.11.0Experimental
+ Supported in ADKPython v1.11.0Java v0.3.0Go v0.3.0Experimental
The ADK Agent Config feature lets you build an ADK workflow without writing
@@ -9,9 +9,9 @@ code. An Agent Config uses a YAML format text file with a brief description of
the agent, allowing just about anyone to assemble and run an ADK agent. The
following is a simple example of a basic Agent Config definition:
-```
+```yaml
name: assistant_agent
-model: gemini-2.5-flash
+model: gemini-flash-latest
description: A helper agent that can answer users' questions.
instruction: You are an agent to help answer users' various questions.
```
@@ -21,7 +21,7 @@ incorporate Functions, Tools, Sub-Agents, and more. This page describes how to
build and run ADK workflows with the Agent Config feature. For detailed
information on the syntax and settings supported by the Agent Config format,
see the
-[Agent Config syntax reference](/adk-docs/api-reference/agentconfig/).
+[Agent Config syntax reference](/api-reference/agentconfig/).
!!! example "Experimental"
The Agent Config feature is experimental and has some
@@ -49,7 +49,7 @@ the Agent Config files.
To set up ADK for use with Agent Config:
1. Install the ADK Python libraries by following the
- [Installation](/adk-docs/get-started/installation/#python)
+ [Installation](/get-started/installation/#python)
instructions. *Python is currently required.* For more information, see the
[Known limitations](#known-limitations).
1. Verify that ADK is installed by running the following command in your
@@ -63,7 +63,7 @@ To set up ADK for use with Agent Config:
If the `adk` command fails to run and the version is not listed in step 2, make
sure your Python environment is active. Execute `source .venv/bin/activate` in
your terminal on Mac and Linux. For other platform commands, see the
- [Installation](/adk-docs/get-started/installation/#python)
+ [Installation](/get-started/installation/#python)
page.
### Build an agent
@@ -110,7 +110,7 @@ To create an ADK project for use with Agent Config:
```
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: assistant_agent
-model: gemini-2.5-flash
+model: gemini-flash-latest
description: A helper agent that can answer users' questions.
instruction: You are an agent to help answer users' various questions.
```
@@ -119,7 +119,7 @@ You can discover more configuration options for your `root_agent.yaml` agent
configuration file by referring to the ADK
[samples repository](https://github.com/search?q=repo%3Agoogle%2Fadk-python+path%3A%2F%5Econtributing%5C%2Fsamples%5C%2F%2F+.yaml&type=code)
or the
-[Agent Config syntax](/adk-docs/api-reference/agentconfig/)
+[Agent Config syntax](/api-reference/agentconfig/)
reference.
### Run the agent
@@ -138,11 +138,45 @@ To run your Agent Config-defined agent:
- `adk api_server` - Run your agent as a service that can be
used by other applications.
-For more information on the ways to run your agent, see the *Run Your Agent*
-topic in the
-[Quickstart](/adk-docs/get-started/quickstart/#run-your-agent).
+For more information on the ways to run your agent, see
+[Agent Runtime](/runtime/#ways-to-run-agents).
For more information about the ADK command line options, see the
-[ADK CLI reference](/adk-docs/api-reference/cli/).
+[ADK CLI reference](/api-reference/cli/).
+
+### Run programmatically
+
+You can also bypass the CLI and dynamically load and execute a configuration-based agent directly in your code. The utility loads the configuration and instantiates the proper agent class (such as `LlmAgent`) transparently as a `BaseAgent` subclass.
+
+=== "Python"
+
+ ```python
+ import asyncio
+ from google.adk.agents import config_agent_utils
+ from google.adk.runners import Runner
+
+ async def main():
+ # Load the agent directly from the YAML config file
+ agent = config_agent_utils.from_config("my_agent/root_agent.yaml")
+ # ...
+
+ if __name__ == "__main__":
+ asyncio.run(main())
+ ```
+
+=== "Java"
+
+ ```java
+ import com.google.adk.agents.BaseAgent;
+ import com.google.adk.agents.ConfigAgentUtils;
+
+ public class AgentApp {
+ public static void main(String[] args) throws Exception {
+ // Load the agent directly from the YAML config file
+ BaseAgent agent = ConfigAgentUtils.fromConfig("my_agent/root_agent.yaml");
+ // ...
+ }
+ }
+ ```
## Example configs
@@ -159,7 +193,7 @@ tool to reply to user requests.
```
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: search_agent
-model: gemini-2.0-flash
+model: gemini-flash-latest
description: 'an agent whose job it is to perform Google search queries and answer questions about the results.'
instruction: You are an agent whose job is to perform Google search queries and answer questions about the results.
tools:
@@ -178,7 +212,7 @@ list of numbers provided by the user are prime numbers.
```
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
agent_class: LlmAgent
-model: gemini-2.5-flash
+model: gemini-flash-latest
name: prime_agent
description: Handles checking if numbers are prime.
instruction: |
@@ -204,7 +238,7 @@ YAML files.
```
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
agent_class: LlmAgent
-model: gemini-2.5-flash
+model: gemini-flash-latest
name: root_agent
description: Learning assistant that provides tutoring in code and math.
instruction: |
@@ -227,12 +261,12 @@ For more details, see the full code for this sample in the
## Deploy agent configs
You can deploy Agent Config agents with
-[Cloud Run](/adk-docs/deploy/cloud-run/) and
-[Agent Engine](/adk-docs/deploy/agent-engine/),
+[Cloud Run](/deploy/cloud-run/) and
+[Agent Runtime](/deploy/agent-runtime/),
using the same procedure as code-based agents. For more information on how
to prepare and deploy Agent Config-based agents, see the
-[Cloud Run](/adk-docs/deploy/cloud-run/) and
-[Agent Engine](/adk-docs/deploy/agent-engine/)
+[Cloud Run](/deploy/cloud-run/) and
+[Agent Runtime](/deploy/agent-runtime/)
deployment guides.
## Known limitations {#known-limitations}
@@ -243,10 +277,11 @@ limitations:
- **Model support:** Only Gemini models are currently supported.
Integration with third-party models is in progress.
- **Programming language:** The Agent Config feature currently supports
- only Python code for tools and other functionality requiring programming code.
+ Python and Java code for tools and other functionality requiring programming code.
- **ADK Tool support:** The following ADK tools are supported by the Agent
Config feature, but *not all tools are fully supported*:
- `google_search`
+ - `google_maps_grounding`
- `load_artifacts`
- `url_context`
- `exit_loop`
@@ -255,13 +290,14 @@ limitations:
- `enterprise_web_search`
- `load_web_page`: Requires a fully-qualified path to access web
pages.
+ - `AgentTool`: Allows an agent to call another agent.
+ - `LongRunningFunctionTool`: Supports long-running functions.
+ - `McpToolset`: Connects to Model Context Protocol (MCP) servers.
+ - `ExampleTool`: Provides example-based few-shot learning for tools.
- **Agent Type Support:** The `LangGraphAgent` and `A2aAgent` types are
not yet supported.
- - `AgentTool`
- - `LongRunningFunctionTool`
- - `VertexAiSearchTool`
- - `McpToolset`
- - `ExampleTool`
+- **Agent Search:** The `VertexAiSearchTool` is currently supported in
+ Python and Java Agent Configs.
## Next steps
@@ -270,4 +306,4 @@ agent definitions in the ADK
[adk-samples](https://github.com/search?q=repo:google/adk-python+path:/%5Econtributing%5C/samples%5C//+root_agent.yaml&type=code)
repository. For detailed information on the syntax and settings supported by
the Agent Config format, see the
-[Agent Config syntax reference](/adk-docs/api-reference/agentconfig/).
+[Agent Config syntax reference](/api-reference/agentconfig/).
diff --git a/docs/agents/custom-agents.md b/docs/agents/custom-agents.md
index d3c9ac6f53..4230e51112 100644
--- a/docs/agents/custom-agents.md
+++ b/docs/agents/custom-agents.md
@@ -344,7 +344,7 @@ These are standard `LlmAgent` definitions, responsible for specific tasks. Their
=== "Python"
```python
- GEMINI_2_FLASH = "gemini-2.0-flash" # Define model constant
+ GEMINI_2_FLASH = "gemini-flash-latest" # Define model constant
--8<-- "examples/python/snippets/agents/custom-agent/storyflow_agent.py:llmagents"
```
diff --git a/docs/agents/index.md b/docs/agents/index.md
index 6afe2fc2ac..dff532e314 100644
--- a/docs/agents/index.md
+++ b/docs/agents/index.md
@@ -46,33 +46,33 @@ Understanding these core types is the first step toward building sophisticated,
Beyond the core agent types, ADK allows you to significantly expand what your
agents can do through several key mechanisms:
-* [**AI Models**](/adk-docs/agents/models/):
+* [**AI Models**](/agents/models/):
Swap the underlying intelligence of your agents by integrating with
different generative AI models from Google and other providers.
-* [**Artifacts**](/adk-docs/artifacts/):
+* [**Artifacts**](/artifacts/):
Enable agents to create and manage persistent outputs like files, code, or
documents that exist beyond the conversation lifecycle.
-* [**Pre-built tools and integrations**](/adk-docs/integrations/):
+* [**Pre-built tools and integrations**](/integrations/):
Equip your agents with a wide array tools, plugins, and other integrations
to interact with the world, including web sites, MCP tools, applications,
databases, programming interfaces, and more.
-* [**Custom tools**](/adk-docs/tools-custom/):
+* [**Custom tools**](/tools-custom/):
Create your own, task-specific tools for solving specific problems with
precision and control.
-* [**Plugins**](/adk-docs/plugins/):
+* [**Plugins**](/plugins/):
Integrate complex, pre-packaged behaviors and third-party services directly
into your agent's workflow.
-* [**Skills**](/adk-docs/skills/):
+* [**Skills**](/skills/):
Use prebuilt or custom [Agent Skills](https://agentskills.io/) to extend
agent capabilities in a way that works efficiently inside AI context window
limits.
-* [**Callbacks**](/adk-docs/callbacks/):
+* [**Callbacks**](/callbacks/):
Hook into specific events during an agent's execution lifecycle to add
logging, monitoring, or custom side-effects without altering core agent
logic.
@@ -86,4 +86,5 @@ Now that you have an overview of the different agent types available in ADK, div
* [**Workflow Agents:**](workflow-agents/index.md) Learn how to orchestrate tasks using `SequentialAgent`, `ParallelAgent`, and `LoopAgent` for structured and predictable processes.
* [**Custom Agents:**](custom-agents.md) Discover the principles of extending `BaseAgent` to build agents with unique logic and integrations tailored to your specific needs.
* [**Multi-Agents:**](multi-agents.md) Understand how to combine different agent types to create sophisticated, collaborative systems capable of tackling complex problems.
-* [**Models:**](/adk-docs/agents/models/) Learn about the different LLM integrations available and how to select the right model for your agents.
+* [**Agent Routing:**](routing.md) Dynamically select between multiple agents at runtime using router functions for fallback, A/B testing, and auto-routing.
+* [**Models:**](/agents/models/) Learn about the different LLM integrations available and how to select the right model for your agents.
diff --git a/docs/agents/llm-agents.md b/docs/agents/llm-agents.md
index d8e57fdb2e..7f87ed543b 100644
--- a/docs/agents/llm-agents.md
+++ b/docs/agents/llm-agents.md
@@ -41,16 +41,16 @@ First, you need to establish what the agent *is* and what it's *for*.
inquiries about current billing statements," not just "Billing agent").
* **`model` (Required):** Specify the underlying LLM that will power this
- agent's reasoning. This is a string identifier like `"gemini-2.5-flash"`. The
+ agent's reasoning. This is a string identifier like `"gemini-flash-latest"`. The
choice of model impacts the agent's capabilities, cost, and performance. See
- the [Models](/adk-docs/agents/models/) page for available options and considerations.
+ the [Models](/agents/models/) page for available options and considerations.
=== "Python"
```python
# Example: Defining the basic identity
capital_agent = LlmAgent(
- model="gemini-2.5-flash",
+ model="gemini-flash-latest",
name="capital_agent",
description="Answers user questions about the capital city of a given country."
# instruction and tools will be added next
@@ -62,7 +62,7 @@ First, you need to establish what the agent *is* and what it's *for*.
```typescript
// Example: Defining the basic identity
const capitalAgent = new LlmAgent({
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
name: 'capital_agent',
description: 'Answers user questions about the capital city of a given country.',
// instruction and tools will be added next
@@ -81,7 +81,7 @@ First, you need to establish what the agent *is* and what it's *for*.
// Example: Defining the basic identity
LlmAgent capitalAgent =
LlmAgent.builder()
- .model("gemini-2.5-flash")
+ .model("gemini-flash-latest")
.name("capital_agent")
.description("Answers user questions about the capital city of a given country.")
// instruction and tools will be added next
@@ -119,7 +119,7 @@ tells the agent:
```python
# Example: Adding instructions
capital_agent = LlmAgent(
- model="gemini-2.5-flash",
+ model="gemini-flash-latest",
name="capital_agent",
description="Answers user questions about the capital city of a given country.",
instruction="""You are an agent that provides the capital city of a country.
@@ -139,7 +139,7 @@ tells the agent:
```typescript
// Example: Adding instructions
const capitalAgent = new LlmAgent({
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
name: 'capital_agent',
description: 'Answers user questions about the capital city of a given country.',
instruction: `You are an agent that provides the capital city of a country.
@@ -166,7 +166,7 @@ tells the agent:
// Example: Adding instructions
LlmAgent capitalAgent =
LlmAgent.builder()
- .model("gemini-2.5-flash")
+ .model("gemini-flash-latest")
.name("capital_agent")
.description("Answers user questions about the capital city of a given country.")
.instruction(
@@ -214,7 +214,7 @@ on the conversation and its instructions.
# Add the tool to the agent
capital_agent = LlmAgent(
- model="gemini-2.5-flash",
+ model="gemini-flash-latest",
name="capital_agent",
description="Answers user questions about the capital city of a given country.",
instruction="""You are an agent that provides the capital city of a country... (previous instruction text)""",
@@ -255,7 +255,7 @@ on the conversation and its instructions.
// Add the tool to the agent
const capitalAgent = new LlmAgent({
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
name: 'capitalAgent',
description: 'Answers user questions about the capital city of a given country.',
instruction: 'You are an agent that provides the capital city of a country...', // Note: the full instruction is omitted for brevity
@@ -294,7 +294,7 @@ on the conversation and its instructions.
FunctionTool capitalTool = FunctionTool.create(experiment.getClass(), "getCapitalCity");
LlmAgent capitalAgent =
LlmAgent.builder()
- .model("gemini-2.5-flash")
+ .model("gemini-flash-latest")
.name("capital_agent")
.description("Answers user questions about the capital city of a given country.")
.instruction("You are an agent that provides the capital city of a country... (previous instruction text)")
@@ -302,7 +302,7 @@ on the conversation and its instructions.
.build();
```
-Learn more about Tools in [Custom Tools](/adk-docs/tools-custom/).
+Learn more about Tools in [Custom Tools](/tools-custom/).
## Advanced Configuration & Control
@@ -381,6 +381,13 @@ For scenarios requiring structured data exchange with an `LLM Agent`, the ADK pr
* **`output_schema` (Optional):** Define a schema representing the desired output structure. If set, the agent's final response *must* be a JSON string conforming to this schema.
+!!! warning "Warning: Using `output_schema` with `tools`"
+
+ Using `output_schema` with `tools` in the same LLM request
+ is only supported by specific models, including [Gemini 3.0](https://ai.google.dev/gemini-api/docs/function-calling?example=meeting#structured-output).
+ For other models, workarounds using [function tools](https://github.com/google/adk-python/blob/main/src/google/adk/flows/llm_flows/_output_schema_processor.py)) in ADK
+ may not work reliably. In such cases, consider using sub-agents that handle output formatting separately.
+
* **`output_key` (Optional):** Provide a string key. If set, the text content of the agent's *final* response will be automatically saved to the session's state dictionary under this key. This is useful for passing results between agents or steps in a workflow.
* In Python, this might look like: `session.state[output_key] = agent_response_text`
* In Java: `session.state().put(outputKey, agentResponseText)`
@@ -464,7 +471,7 @@ For scenarios requiring structured data exchange with an `LLM Agent`, the ADK pr
// ... name, model, description
.instruction(
"You are a Capital Information Agent. Given a country, respond ONLY with a JSON object containing the capital. Format: {\"capital\": \"capital_name\"}")
- .outputSchema(capitalOutput) // Enforce JSON output
+ .outputSchema(CAPITAL_OUTPUT) // Enforce JSON output
.outputKey("found_capital") // Store result in state.get("found_capital")
// Cannot use tools(getCapitalCity) effectively here
.build();
@@ -534,7 +541,7 @@ Control whether the agent receives the prior conversation history.
from google.genai import types
my_agent = Agent(
- model="gemini-2.5-flash",
+ model="gemini-flash-latest",
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(
include_thoughts=True,
@@ -552,7 +559,7 @@ Control whether the agent receives the prior conversation history.
from google.adk.planners import PlanReActPlanner
my_agent = Agent(
- model="gemini-2.5-flash",
+ model="gemini-flash-latest",
planner=PlanReActPlanner(),
# ... your tools here
)
@@ -703,7 +710,7 @@ call_agent("If it's raining in New York right now, what is the current temperatu
- **`code_executor` (Optional):** Provide a `BaseCodeExecutor` instance to allow
the agent to execute code blocks found in the LLM's response. For more
- information, see [Code Execution with Gemini API](/adk-docs/tools/gemini-api/code-execution/).
+ information, see [Code Execution with Gemini API](/integrations/code-execution/).
=== "Python"
diff --git a/docs/agents/models/vertex.md b/docs/agents/models/agent-platform.md
similarity index 54%
rename from docs/agents/models/vertex.md
rename to docs/agents/models/agent-platform.md
index 3d40b60bd9..9ab23cc0be 100644
--- a/docs/agents/models/vertex.md
+++ b/docs/agents/models/agent-platform.md
@@ -1,16 +1,16 @@
-# Vertex AI hosted models for ADK agents
+# Agent Platform hosted models for ADK agents
For enterprise-grade scalability, reliability, and integration with Google
-Cloud's MLOps ecosystem, you can use models deployed to Vertex AI Endpoints.
+Cloud's MLOps ecosystem, you can use models deployed to Agent Platform Endpoints.
This includes models from Model Garden or your own fine-tuned models.
-**Integration Method:** Pass the full Vertex AI Endpoint resource string
+**Integration Method:** Pass the full Agent Platform Endpoint resource string
(`projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID`) directly to the
`model` parameter of `LlmAgent`.
-## Vertex AI Setup
+## Agent Platform Setup
-Ensure your environment is configured for Vertex AI:
+Ensure your environment is configured for Agent Platform:
1. **Authentication:** Use Application Default Credentials (ADC):
@@ -25,8 +25,8 @@ Ensure your environment is configured for Vertex AI:
export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # e.g., us-central1
```
-3. **Enable Vertex Backend:** Crucially, ensure the `google-genai` library
- targets Vertex AI:
+3. **Enable Agent Platform Backend:** Crucially, ensure the `google-genai` library
+ targets Agent Platform:
```shell
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
@@ -35,68 +35,120 @@ Ensure your environment is configured for Vertex AI:
## Model Garden Deployments
- Supported in ADKPython v0.2.0
+ Supported in ADKPython v0.2.0Java v0.1.0
You can deploy various open and proprietary models from the
-[Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)
+[Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)
to an endpoint.
**Example:**
-```python
-from google.adk.agents import LlmAgent
-from google.genai import types # For config objects
+=== "Python"
+
+ ```python
+ from google.adk.agents import LlmAgent
+ from google.genai import types # For config objects
+
+ # --- Example Agent using a Llama 3 model deployed from Model Garden ---
-# --- Example Agent using a Llama 3 model deployed from Model Garden ---
+ # Replace with your actual Agent Platform Endpoint resource name
+ llama3_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_LLAMA3_ENDPOINT_ID"
-# Replace with your actual Vertex AI Endpoint resource name
-llama3_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_LLAMA3_ENDPOINT_ID"
+ agent_llama3_vertex = LlmAgent(
+ model=llama3_endpoint,
+ name="llama3_vertex_agent",
+ instruction="You are a helpful assistant based on Llama 3, hosted on Agent Platform.",
+ generate_content_config=types.GenerateContentConfig(max_output_tokens=2048),
+ # ... other agent parameters
+ )
+ ```
-agent_llama3_vertex = LlmAgent(
- model=llama3_endpoint,
- name="llama3_vertex_agent",
- instruction="You are a helpful assistant based on Llama 3, hosted on Vertex AI.",
- generate_content_config=types.GenerateContentConfig(max_output_tokens=2048),
- # ... other agent parameters
-)
-```
+=== "Java"
+
+ ```java
+ import com.google.adk.agents.LlmAgent;
+ import com.google.adk.models.Gemini;
+ import com.google.genai.types.GenerateContentConfig;
+
+ // ...
+
+ // Replace with your actual Agent Platform Endpoint resource name
+ String llama3Endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_LLAMA3_ENDPOINT_ID";
+
+ LlmAgent agentLlama3Vertex = LlmAgent.builder()
+ .model(Gemini.builder()
+ .modelName(llama3Endpoint)
+ .build())
+ .name("llama3_vertex_agent")
+ .instruction("You are a helpful assistant based on Llama 3, hosted on Agent Platform.")
+ .generateContentConfig(GenerateContentConfig.builder()
+ .maxOutputTokens(2048)
+ .build())
+ // ... other agent parameters
+ .build();
+ ```
## Fine-tuned Model Endpoints
- Supported in ADKPython v0.2.0
+ Supported in ADKPython v0.2.0Java v0.1.0
Deploying your fine-tuned models (whether based on Gemini or other architectures
-supported by Vertex AI) results in an endpoint that can be used directly.
+supported by Agent Platform) results in an endpoint that can be used directly.
**Example:**
-```python
-from google.adk.agents import LlmAgent
+=== "Python"
-# --- Example Agent using a fine-tuned Gemini model endpoint ---
+ ```python
+ from google.adk.agents import LlmAgent
-# Replace with your fine-tuned model's endpoint resource name
-finetuned_gemini_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_FINETUNED_ENDPOINT_ID"
+ # --- Example Agent using a fine-tuned Gemini model endpoint ---
-agent_finetuned_gemini = LlmAgent(
- model=finetuned_gemini_endpoint,
- name="finetuned_gemini_agent",
- instruction="You are a specialized assistant trained on specific data.",
- # ... other agent parameters
-)
-```
+ # Replace with your fine-tuned model's endpoint resource name
+ finetuned_gemini_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_FINETUNED_ENDPOINT_ID"
-## Anthropic Claude on Vertex AI {#third-party-models-on-vertex-ai-eg-anthropic-claude}
+ agent_finetuned_gemini = LlmAgent(
+ model=finetuned_gemini_endpoint,
+ name="finetuned_gemini_agent",
+ instruction="You are a specialized assistant trained on specific data.",
+ # ... other agent parameters
+ )
+ ```
+
+=== "Java"
+
+ ```java
+ import com.google.adk.agents.LlmAgent;
+ import com.google.adk.models.Gemini;
+
+ // ...
+
+ // Replace with your fine-tuned model's endpoint resource name
+ String finetunedGeminiEndpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_FINETUNED_ENDPOINT_ID";
+
+ LlmAgent agentFinetunedGemini = LlmAgent.builder()
+ .model(Gemini.builder()
+ .modelName(finetunedGeminiEndpoint)
+ .build())
+ .name("finetuned_gemini_agent")
+ .instruction("You are a specialized assistant trained on specific data.")
+ // ... other agent parameters
+ .build();
+ ```
+
+## Anthropic Claude on Agent Platform {#anthropic-claude}
Supported in ADKPython v0.2.0Java v0.1.0
Some providers, like Anthropic, make their models available directly through
-Vertex AI.
+Agent Platform.
+
+**Example:**
=== "Python"
@@ -104,19 +156,19 @@ Vertex AI.
`"claude-3-sonnet@20240229"`), *but requires manual registration* within ADK.
**Why Registration?** ADK's registry automatically recognizes `gemini-*` strings
- and standard Vertex AI endpoint strings (`projects/.../endpoints/...`) and
+ and standard Agent Platform endpoint strings (`projects/.../endpoints/...`) and
routes them via the `google-genai` library. For other model types used directly
- via Vertex AI (like Claude), you must explicitly tell the ADK registry which
+ via Agent Platform (like Claude), you must explicitly tell the ADK registry which
specific wrapper class (`Claude` in this case) knows how to handle that model
- identifier string with the Vertex AI backend.
+ identifier string with the Agent Platform backend.
**Setup:**
- 1. **Vertex AI Environment:** Ensure the consolidated Vertex AI setup (ADC, Env
+ 1. **Agent Platform Environment:** Ensure the consolidated Agent Platform setup (ADC, Env
Vars, `GOOGLE_GENAI_USE_VERTEXAI=TRUE`) is complete.
2. **Install Provider Library:** Install the necessary client library configured
- for Vertex AI.
+ for Agent Platform.
```shell
pip install "anthropic[vertex]"
@@ -126,15 +178,13 @@ Vertex AI.
*before* creating an agent using the Claude model string:
```python
- # Required for using Claude model strings directly via Vertex AI with LlmAgent
+ # Required for using Claude model strings directly via Agent Platform with LlmAgent
from google.adk.models.anthropic_llm import Claude
from google.adk.models.registry import LLMRegistry
LLMRegistry.register(Claude)
```
- **Example:**
-
```python
from google.adk.agents import LlmAgent
from google.adk.models.anthropic_llm import Claude # Import needed for registration
@@ -144,15 +194,15 @@ Vertex AI.
# --- Register Claude class (do this once at startup) ---
LLMRegistry.register(Claude)
- # --- Example Agent using Claude 3 Sonnet on Vertex AI ---
+ # --- Example Agent using Claude 3 Sonnet on Agent Platform ---
- # Standard model name for Claude 3 Sonnet on Vertex AI
+ # Standard model name for Claude 3 Sonnet on Agent Platform
claude_model_vertexai = "claude-3-sonnet@20240229"
agent_claude_vertexai = LlmAgent(
model=claude_model_vertexai, # Pass the direct string after registration
name="claude_vertexai_agent",
- instruction="You are an assistant powered by Claude 3 Sonnet on Vertex AI.",
+ instruction="You are an assistant powered by Claude 3 Sonnet on Agent Platform.",
generate_content_config=types.GenerateContentConfig(max_output_tokens=4096),
# ... other agent parameters
)
@@ -160,24 +210,22 @@ Vertex AI.
=== "Java"
- **Integration Method:** Directly instantiate the provider-specific model class (e.g., `com.google.adk.models.Claude`) and configure it with a Vertex AI backend.
+ **Integration Method:** Directly instantiate the provider-specific model class (e.g., `com.google.adk.models.Claude`) and configure it with an Agent Platform backend.
- **Why Direct Instantiation?** The Java ADK's `LlmRegistry` primarily handles Gemini models by default. For third-party models like Claude on Vertex AI, you directly provide an instance of the ADK's wrapper class (e.g., `Claude`) to the `LlmAgent`. This wrapper class is responsible for interacting with the model via its specific client library, configured for Vertex AI.
+ **Why Direct Instantiation?** The Java ADK's `LlmRegistry` primarily handles Gemini models by default. For third-party models like Claude on Agent Platform, you directly provide an instance of the ADK's wrapper class (e.g., `Claude`) to the `LlmAgent`. This wrapper class is responsible for interacting with the model via its specific client library, configured for Agent Platform.
**Setup:**
- 1. **Vertex AI Environment:**
+ 1. **Agent Platform Environment:**
* Ensure your Google Cloud project and region are correctly set up.
- * **Application Default Credentials (ADC):** Make sure ADC is configured correctly in your environment. This is typically done by running `gcloud auth application-default login`. The Java client libraries use these credentials to authenticate with Vertex AI. Follow the [Google Cloud Java documentation on ADC](https://cloud.google.com/java/docs/reference/google-auth-library/latest/com.google.auth.oauth2.GoogleCredentials#com_google_auth_oauth2_GoogleCredentials_getApplicationDefault__) for detailed setup.
+ * **Application Default Credentials (ADC):** Make sure ADC is configured correctly in your environment. This is typically done by running `gcloud auth application-default login`. The Java client libraries use these credentials to authenticate with Agent Platform. Follow the [Google Cloud Java documentation on ADC](https://cloud.google.com/java/docs/reference/google-auth-library/latest/com.google.auth.oauth2.GoogleCredentials#com_google_auth_oauth2_GoogleCredentials_getApplicationDefault__) for detailed setup.
2. **Provider Library Dependencies:**
- * **Third-Party Client Libraries (Often Transitive):** The ADK core library often includes the necessary client libraries for common third-party models on Vertex AI (like Anthropic's required classes) as **transitive dependencies**. This means you might not need to explicitly add a separate dependency for the Anthropic Vertex SDK in your `pom.xml` or `build.gradle`.
+ * **Third-Party Client Libraries (Often Transitive):** The ADK core library often includes the necessary client libraries for common third-party models on Agent Platform (like Anthropic's required classes) as **transitive dependencies**. This means you might not need to explicitly add a separate dependency for the Anthropic Vertex SDK in your `pom.xml` or `build.gradle`.
3. **Instantiate and Configure the Model:**
When creating your `LlmAgent`, instantiate the `Claude` class (or the equivalent for another provider) and configure its `VertexBackend`.
- **Example:**
-
```java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
@@ -192,14 +240,14 @@ Vertex AI.
public class ClaudeVertexAiAgent {
public static LlmAgent createAgent() throws IOException {
- // Model name for Claude 3 Sonnet on Vertex AI (or other versions)
+ // Model name for Claude 3 Sonnet on Agent Platform (or other versions)
String claudeModelVertexAi = "claude-3-7-sonnet"; // Or any other Claude model
// Configure the AnthropicOkHttpClient with the VertexBackend
AnthropicClient anthropicClient = AnthropicOkHttpClient.builder()
.backend(
VertexBackend.builder()
- .region("us-east5") // Specify your Vertex AI region
+ .region("us-east5") // Specify your Agent Platform region
.project("your-gcp-project-id") // Specify your GCP Project ID
.googleCredentials(GoogleCredentials.getApplicationDefault())
.build())
@@ -209,7 +257,7 @@ Vertex AI.
LlmAgent agentClaudeVertexAi = LlmAgent.builder()
.model(new Claude(claudeModelVertexAi, anthropicClient)) // Pass the Claude instance
.name("claude_vertexai_agent")
- .instruction("You are an assistant powered by Claude 3 Sonnet on Vertex AI.")
+ .instruction("You are an assistant powered by Claude 3 Sonnet on Agent Platform.")
// .generateContentConfig(...) // Optional: Add generation config if needed
// ... other agent parameters
.build();
@@ -230,31 +278,31 @@ Vertex AI.
}
```
-## Open Models on Vertex AI {#open-models}
+## Open Models on Agent Platform {#open-models}
- Supported in ADKPython v0.1.0
+ Supported in ADKPython v0.1.0Java v0.1.0
-Vertex AI offers a curated selection of open-source models, such as Meta Llama, through Model-as-a-Service (MaaS). These models are accessible via managed APIs, allowing you to deploy and scale without managing the underlying infrastructure. For a full list of available options, see the [Vertex AI open models for MaaS](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/maas/use-open-models#open-models) documentation.
+Agent Platform offers a curated selection of open-source models, such as Meta Llama, through Model-as-a-Service (MaaS). These models are accessible via managed APIs, allowing you to deploy and scale without managing the underlying infrastructure. For a full list of available options, see the [Agent Platform open models for MaaS](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/maas/use-open-models#open-models) documentation.
=== "Python"
- You can use the [LiteLLM](https://docs.litellm.ai/) library to access open models like Meta's Llama on VertexAI MaaS
+ You can use the [LiteLLM](https://docs.litellm.ai/) library to access open models like Meta's Llama on Agent Platform MaaS
**Integration Method:** Use the `LiteLlm` wrapper class and set it
- as the `model` parameter of `LlmAgent`. Make sure you go through the [LiteLLM model connector for ADK agents](/adk-docs/agents/models/litellm/#litellm-model-connector-for-adk-agents) documentation on how to use LiteLLM in ADK
+ as the `model` parameter of `LlmAgent`. Make sure you go through the [LiteLLM model connector for ADK agents](/agents/models/litellm/#litellm-model-connector-for-adk-agents) documentation on how to use LiteLLM in ADK
**Setup:**
- 1. **Vertex AI Environment:** Ensure the consolidated Vertex AI setup (ADC, Env
+ 1. **Agent Platform Environment:** Ensure the consolidated Agent Platform setup (ADC, Env
Vars, `GOOGLE_GENAI_USE_VERTEXAI=TRUE`) is complete.
2. **Install LiteLLM:**
```shell
pip install litellm
```
-
+
**Example:**
```python
diff --git a/docs/agents/models/anthropic.md b/docs/agents/models/anthropic.md
index 416c8cd23b..5f9b95e8dd 100644
--- a/docs/agents/models/anthropic.md
+++ b/docs/agents/models/anthropic.md
@@ -5,16 +5,16 @@
You can integrate Anthropic's Claude models directly using an Anthropic API key
-or from a Vertex AI backend into your Java ADK applications by using the ADK's
+or from an Agent Platform backend into your Java ADK applications by using the ADK's
`Claude` wrapper class. You can also access Anthropic models through
-Google Cloud Vertex AI services. For more information, see the
-[Third-Party Models on Vertex AI](/adk-docs/agents/models/vertex/#third-party-models-on-vertex-ai-eg-anthropic-claude)
+Google Cloud Agent Platform services. For more information, see the
+[Third-Party Models on Agent Platform](/agents/models/agent-platform/#anthropic-claude)
section. You can also use Anthropic models through the
-[LiteLLM](/adk-docs/agents/models/litellm/) library for Python.
+[LiteLLM](/agents/models/litellm/) library for Python.
## Get started
-The following code examples show a basic implementation for using Gemini models
+The following code examples show a basic implementation for using Anthropic models
in your agents:
```java
@@ -25,7 +25,7 @@ public static LlmAgent createAgent() {
.build();
Claude claudeModel = new Claude(
- "claude-3-7-sonnet-latest", anthropicClient
+ "claude-sonnet-4-6", anthropicClient
);
return LlmAgent.builder()
@@ -61,7 +61,7 @@ import com.anthropic.client.okhttp.AnthropicOkHttpClient; // From Anthropic's SD
public class DirectAnthropicAgent {
- private static final String CLAUDE_MODEL_ID = "claude-3-7-sonnet-latest"; // Or your preferred Claude model
+ private static final String CLAUDE_MODEL_ID = "claude-sonnet-4-6"; // Or your preferred Claude model
public static LlmAgent createAgent() {
diff --git a/docs/agents/models/apigee.md b/docs/agents/models/apigee.md
index a0c3a7ccac..1ec45bface 100644
--- a/docs/agents/models/apigee.md
+++ b/docs/agents/models/apigee.md
@@ -7,7 +7,7 @@
[Apigee](https://docs.cloud.google.com/apigee/docs/api-platform/get-started/what-apigee)
provides a powerful [AI Gateway](https://cloud.google.com/solutions/apigee-ai),
transforming how you manage and govern your generative AI model traffic. By
-exposing your AI model endpoint (like Vertex AI or the Gemini API) through an
+exposing your AI model endpoint (like Agent Platform or the Gemini API) through an
Apigee proxy, you immediately gain enterprise-grade capabilities:
- **Model Safety:** Implement security policies like Model Armor for threat protection.
@@ -20,7 +20,7 @@ Apigee proxy, you immediately gain enterprise-grade capabilities:
!!! note
- The `ApigeeLLM` wrapper is currently designed for use with Vertex AI
+ The `ApigeeLLM` wrapper is currently designed for use with Agent Platform
and the Gemini API (generateContent). We are continually expanding support for
other models and interfaces.
@@ -39,7 +39,7 @@ Integrate Apigee's governance into your agent's workflow by instantiating the
# Instantiate the ApigeeLlm wrapper
model = ApigeeLlm(
# Specify the Apigee route to your model. For more info, check out the ApigeeLlm documentation (https://github.com/google/adk-python/tree/main/contributing/samples/hello_world_apigeellm).
- model="apigee/gemini-2.5-flash",
+ model="apigee/gemini-flash-latest",
# The proxy URL of your deployed Apigee proxy including the base path
proxy_url=f"https://{APIGEE_PROXY_URL}",
# Pass necessary authentication/authorization headers (like an API key)
@@ -65,7 +65,7 @@ Integrate Apigee's governance into your agent's workflow by instantiating the
ApigeeLlm apigeeLlm =
ApigeeLlm.builder()
- .modelName("apigee/gemini-2.5-flash") // Specify the Apigee route to your model. For more info, check out the ApigeeLlm documentation
+ .modelName("apigee/gemini-flash-latest") // Specify the Apigee route to your model. For more info, check out the ApigeeLlm documentation
.proxyUrl(APIGEE_PROXY_URL) //The proxy URL of your deployed Apigee proxy including the base path
.customHeaders(ImmutableMap.of("foo", "bar")) //Pass necessary authentication/authorization headers (like an API key)
.build();
diff --git a/docs/agents/models/google-gemini.md b/docs/agents/models/google-gemini.md
index c70f5a3beb..97b9d1c655 100644
--- a/docs/agents/models/google-gemini.md
+++ b/docs/agents/models/google-gemini.md
@@ -7,10 +7,10 @@
ADK supports the Google Gemini family of generative AI models that provide a
powerful set of models with a wide range of features. ADK provides support for many
Gemini features, including
-[Code Execution](/adk-docs/tools/gemini-api/code-execution/),
-[Google Search](/adk-docs/tools/gemini-api/google-search/),
-[Context caching](/adk-docs/context/caching/),
-[Computer use](/adk-docs/tools/gemini-api/computer-use/)
+[Code Execution](/integrations/code-execution/),
+[Google Search](/integrations/google-search/),
+[Context caching](/context/caching/),
+[Computer use](/integrations/computer-use/)
and the [Interactions API](#interactions-api).
## Get started
@@ -26,7 +26,7 @@ in your agents:
# --- Example using a stable Gemini Flash model ---
agent_gemini_flash = LlmAgent(
# Use the latest stable Flash model identifier
- model="gemini-2.5-flash",
+ model="gemini-flash-latest",
name="gemini_flash_agent",
instruction="You are a fast and helpful Gemini assistant.",
# ... other agent parameters
@@ -41,7 +41,7 @@ in your agents:
// --- Example #2: using a powerful Gemini Pro model with API Key in model ---
export const rootAgent = new LlmAgent({
name: 'hello_time_agent',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
description: 'Gemini flash agent',
instruction: `You are a fast and helpful Gemini assistant.`,
});
@@ -66,17 +66,26 @@ in your agents:
LlmAgent agentGeminiFlash =
LlmAgent.builder()
// Use the latest stable Flash model identifier
- .model("gemini-2.5-flash") // Set ENV variables to use this model
+ .model("gemini-flash-latest") // Set ENV variables to use this model
.name("gemini_flash_agent")
.instruction("You are a fast and helpful Gemini assistant.")
// ... other agent parameters
.build();
```
+??? note "Note: Gemini model selector `gemini-flash-latest`"
+
+ Most code examples in ADK documentation use `gemini-flash-latest` to select the
+ [latest available](https://ai.google.dev/gemini-api/docs/models#latest)
+ Gemini Flash version. However, if you access Gemini from a regional endpoint,
+ such as `us-central1`, this selection string may not work. In that case,
+ use a specific model version string from the
+ [Gemini models](https://ai.google.dev/gemini-api/docs/models) page or
+ Google Cloud [Gemini models](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models) list.
## Gemini model authentication
-This section covers authenticating with Google's Gemini models, either through Google AI Studio for rapid development or Google Cloud Vertex AI for enterprise applications. This is the most direct way to use Google's flagship models within ADK.
+This section covers authenticating with Google's Gemini models, either through Google AI Studio for rapid development or Google Cloud Agent Platform for enterprise applications. This is the most direct way to use Google's flagship models within ADK.
**Integration Method:** Once you are authenticated using one of the below methods, you can pass the model's identifier string directly to the
`model` parameter of `LlmAgent`.
@@ -85,7 +94,7 @@ This section covers authenticating with Google's Gemini models, either through G
!!! tip
The `google-genai` library, used internally by ADK for Gemini models, can connect
- through either Google AI Studio or Vertex AI.
+ through either Google AI Studio or Agent Platform.
**Model support for voice/video streaming**
@@ -94,7 +103,7 @@ This section covers authenticating with Google's Gemini models, either through G
support the Gemini Live API in the documentation:
- [Google AI Studio: Gemini Live API](https://ai.google.dev/gemini-api/docs/models#live-api)
- - [Vertex AI: Gemini Live API](https://cloud.google.com/vertex-ai/generative-ai/docs/live-api)
+ - [Agent Platform: Gemini Live API](https://cloud.google.com/vertex-ai/generative-ai/docs/live-api)
### Google AI Studio
@@ -117,11 +126,11 @@ This is the simplest method and is recommended for getting started quickly.
* **Models:** Find all available models on the
[Google AI for Developers site](https://ai.google.dev/gemini-api/docs/models).
-### Google Cloud Vertex AI
+### Google Cloud Agent Platform
-For scalable and production-oriented use cases, Vertex AI is the recommended platform. Gemini on Vertex AI supports enterprise-grade features, security, and compliance controls. Based on your development environment and usecase, *choose one of the below methods to authenticate*.
+For scalable and production-oriented use cases, Agent Platform is the recommended platform. Gemini on Agent Platform supports enterprise-grade features, security, and compliance controls. Based on your development environment and usecase, *choose one of the below methods to authenticate*.
-**Pre-requisites:** A Google Cloud Project with [Vertex AI enabled](https://console.cloud.google.com/apis/enableflow;apiid=aiplatform.googleapis.com).
+**Pre-requisites:** A Google Cloud Project with [Agent Platform enabled](https://console.cloud.google.com/apis/enableflow;apiid=aiplatform.googleapis.com).
### **Method A: User Credentials (for Local Development)**
@@ -136,22 +145,22 @@ For scalable and production-oriented use cases, Vertex AI is the recommended pla
export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # e.g., us-central1
```
- Explicitly tell the library to use Vertex AI:
+ Explicitly tell the library to use Agent Platform:
```shell
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
```
4. **Models:** Find available model IDs in the
- [Vertex AI documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models).
+ [Agent Platform documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models).
-### **Method B: Vertex AI Express Mode**
-[Vertex AI Express Mode](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) offers a simplified, API-key-based setup for rapid prototyping.
+### **Method B: Agent Platform Express Mode**
+[Agent Platform Express Mode](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) offers a simplified, API-key-based setup for rapid prototyping.
1. **Sign up for Express Mode** to get your API key.
2. **Set environment variables:**
```shell
- export GOOGLE_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
+ export GOOGLE_GENAI_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
```
@@ -159,7 +168,7 @@ For scalable and production-oriented use cases, Vertex AI is the recommended pla
For deployed applications, a service account is the standard method.
-1. [**Create a Service Account**](https://cloud.google.com/iam/docs/service-accounts-create#console) and grant it the `Vertex AI User` role.
+1. [**Create a Service Account**](https://cloud.google.com/iam/docs/service-accounts-create#console) and grant it the `Agent Platform User` role.
2. **Provide credentials to your application:**
* **On Google Cloud:** If you are running the agent in Cloud Run, GKE, VM or other Google Cloud services, the environment can automatically provide the service account credentials. You don't have to create a key file.
* **Elsewhere:** Create a [service account key file](https://cloud.google.com/iam/docs/keys-create-delete#console) and point to it with an environment variable:
@@ -200,37 +209,89 @@ To mitigate this, you can do one of the following:
You would use this option if you are instantiating this model adapter by
yourself.
- ```python
- root_agent = Agent(
- model='gemini-2.5-flash',
- ...
- generate_content_config=types.GenerateContentConfig(
- ...
- http_options=types.HttpOptions(
- ...
- retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
- ...
- ),
- ...
- )
- ```
+ === "Python"
+
+ ```python
+ root_agent = Agent(
+ model='gemini-flash-latest',
+ # ...
+ generate_content_config=types.GenerateContentConfig(
+ # ...
+ http_options=types.HttpOptions(
+ # ...
+ retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
+ # ...
+ ),
+ # ...
+ )
+ ```
+
+ === "Java"
+
+ ```java
+ import com.google.adk.agents.LlmAgent;
+ import com.google.genai.types.GenerateContentConfig;
+ import com.google.genai.types.HttpOptions;
+ import com.google.genai.types.HttpRetryOptions;
+
+ // ...
+
+ LlmAgent rootAgent = LlmAgent.builder()
+ .model("gemini-flash-latest")
+ // ...
+ .generateContentConfig(GenerateContentConfig.builder()
+ // ...
+ .httpOptions(HttpOptions.builder()
+ // ...
+ .retryOptions(HttpRetryOptions.builder().initialDelay(1.0).attempts(2).build())
+ // ...
+ .build())
+ // ...
+ .build())
+ .build();
+ ```
**Option 2:** Retry options on this model adapter.
You would use this option if you were instantiating the instance of adapter
by yourself.
- ```python
- from google.genai import types
+ === "Python"
- # ...
+ ```python
+ from google.genai import types
- agent = Agent(
- model=Gemini(
- retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
+ # ...
+
+ agent = Agent(
+ model=Gemini(
+ retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
+ )
)
- )
- ```
+ ```
+
+ === "Java"
+
+ ```java
+ import com.google.adk.agents.LlmAgent;
+ import com.google.adk.models.Gemini;
+ import com.google.genai.Client;
+ import com.google.genai.types.HttpOptions;
+ import com.google.genai.types.HttpRetryOptions;
+
+ // ...
+
+ LlmAgent agent = LlmAgent.builder()
+ .model(Gemini.builder()
+ .modelName("gemini-flash-latest")
+ .apiClient(Client.builder()
+ .httpOptions(HttpOptions.builder()
+ .retryOptions(HttpRetryOptions.builder().initialDelay(1.0).attempts(2).build())
+ .build())
+ .build())
+ .build())
+ .build();
+ ```
## Gemini Interactions API {#interactions-api}
@@ -248,23 +309,45 @@ You can enable the Interactions API by setting the `use_interactions_api=True`
parameter in the Gemini model configuration, as shown in the following code
snippet:
-```python
-from google.adk.agents.llm_agent import Agent
-from google.adk.models.google_llm import Gemini
-from google.adk.tools.google_search_tool import GoogleSearchTool
-
-root_agent = Agent(
- model=Gemini(
- model="gemini-2.5-flash",
- use_interactions_api=True, # Enable Interactions API
- ),
- name="interactions_test_agent",
- tools=[
- GoogleSearchTool(bypass_multi_tools_limit=True), # Converted to function tool
- get_current_weather, # Custom function tool
- ],
-)
-```
+=== "Python"
+
+ ```python
+ from google.adk.agents.llm_agent import Agent
+ from google.adk.models.google_llm import Gemini
+ from google.adk.tools.google_search_tool import GoogleSearchTool
+
+ root_agent = Agent(
+ model=Gemini(
+ model="gemini-flash-latest",
+ use_interactions_api=True, # Enable Interactions API
+ ),
+ name="interactions_test_agent",
+ tools=[
+ GoogleSearchTool(bypass_multi_tools_limit=True), # Converted to function tool
+ get_current_weather, # Custom function tool
+ ],
+ )
+ ```
+
+=== "Java"
+
+ ```java
+ import com.google.adk.agents.LlmAgent;
+ import com.google.adk.models.Gemini;
+ import com.google.adk.tools.GoogleSearchTool;
+
+ // Note: Interactions API support in Java ADK is currently under development.
+ LlmAgent rootAgent = LlmAgent.builder()
+ .model(Gemini.builder()
+ .modelName("gemini-flash-latest")
+ .build())
+ .name("interactions_test_agent")
+ .tools(
+ GoogleSearchTool.INSTANCE, // Search tool
+ getCurrentWeather // Custom function tool
+ )
+ .build();
+ ```
For a complete code sample, see the
[Interactions API sample](https://github.com/google/adk-python/tree/main/contributing/samples/interactions_api).
@@ -273,15 +356,25 @@ For a complete code sample, see the
The Interactions API **does not** support mixing custom function calling tools with
built-in tools, such as the
-[Google Search](/adk-docs/tools/built-in-tools/#google-search),
+[Google Search](/integrations/google-search/),
tool, within the same agent. You can work around this limitation by configuring the
the built-in tool to operate as a custom tool using the `bypass_multi_tools_limit`
parameter:
-```python
-# Use bypass_multi_tools_limit=True to convert google_search to a function tool
-GoogleSearchTool(bypass_multi_tools_limit=True)
-```
+=== "Python"
+
+ ```python
+ # Use bypass_multi_tools_limit=True to convert google_search to a function tool
+ GoogleSearchTool(bypass_multi_tools_limit=True)
+ ```
+
+=== "Java"
+
+ ```java
+ // Note: bypassMultiToolsLimit is Python-specific.
+ // In Java, simply use the tool instance.
+ GoogleSearchTool.INSTANCE;
+ ```
In this example, this option converts the built-in google_search to a function
calling tool (via GoogleSearchAgentTool), which allows it to work alongside
diff --git a/docs/agents/models/google-gemma.md b/docs/agents/models/google-gemma.md
new file mode 100644
index 0000000000..e65aaf6be0
--- /dev/null
+++ b/docs/agents/models/google-gemma.md
@@ -0,0 +1,316 @@
+# Google Gemma models for ADK agents
+
+
+ Supported in ADKPython v0.1.0
+
+
+ADK agents can use the [Google Gemma](https://ai.google.dev/gemma/docs) family of generative AI models that offer a
+wide range of capabilities. ADK supports many Gemma features,
+including [Tool Calling](/tools-custom/)
+and [Structured Output](/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key).
+
+You can use Gemma 4 through the [Gemini API](https://ai.google.dev/gemini-api/docs),
+or with one of many self-hosting options on Google Cloud:
+[Agent Platform](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/gemma4),
+[Google Kubernetes Engine](https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/serve-gemma-gpu-vllm),
+[Cloud Run](https://docs.cloud.google.com/run/docs/run-gemma-on-cloud-run).
+
+## Gemini API Example
+
+Create an API key in [Google AI Studio](https://aistudio.google.com/app/apikey).
+
+=== "Python"
+ ```python
+ # Set GEMINI_API_KEY environment variable to your API key
+ # export GEMINI_API_KEY="YOUR_API_KEY"
+
+ from google.adk.agents import LlmAgent
+ from google.adk.models import Gemini
+
+ # Simple tool to try
+ def get_weather(location: str) -> str:
+ return f"Location: {location}. Weather: sunny, 76 degrees Fahrenheit, 8 mph wind."
+
+ root_agent = LlmAgent(
+ model=Gemini(model="gemma-4-31b-it"),
+ name="weather_agent",
+ instruction="You are a helpful assistant that can provide current weather.",
+ tools=[get_weather]
+ )
+ ```
+
+=== "Java"
+ ```java
+ // Set GEMINI_API_KEY environment variable to your API key
+ // export GEMINI_API_KEY="YOUR_API_KEY"
+
+ import com.google.adk.agents.LlmAgent;
+ import com.google.adk.tools.Annotations.Schema;
+ import com.google.adk.tools.FunctionTool;
+
+ LlmAgent weatherAgent = LlmAgent.builder()
+ .model("gemma-4-31b-it")
+ .name("weather_agent")
+ .instruction("""
+ You are a helpful assistant that can provide current weather.
+ """)
+ .tools(FunctionTool.create(this, "getWeather")]
+ .build();
+
+ @Schema(name = "getWeather",
+ description = "Retrieve the weather forecast for a given location")
+ public Map getWeather(
+ @Schema(name = "location",
+ description = "The location for the weather forecast")
+ String location) {
+ return Map.of("forecast", "Location: " + location
+ + ". Weather: sunny, 76 degrees Fahrenheit, 8 mph wind.");
+ }
+ ```
+
+## vLLM Example
+
+To access Gemma 4 endpoints in these services,
+you can use vLLM models through the [LiteLLM](/agents/models/litellm/) library for Python,
+and through [LangChain4j](https://docs.langchain4j.dev/) for Java.
+
+The following example shows how to use a Gemma 4 vLLM endpoint with ADK agents.
+
+### Setup
+
+1. **Deploy Model:** Deploy your chosen model using
+ [Agent Platform](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/gemma4),
+ [Google Kubernetes Engine](https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/serve-gemma-gpu-vllm),
+ or [Cloud Run](https://docs.cloud.google.com/run/docs/run-gemma-on-cloud-run),
+ and use its OpenAI-compatible API endpoint.
+ Note that the API base URL includes `/v1` (e.g., `https://your-vllm-endpoint.run.app/v1`).
+ * *Important for ADK Tools:* When deploying, ensure the serving tool
+ supports and enables compatible tool/function calling and reasoning parsers.
+2. **Authentication:** Determine how your endpoint handles authentication (e.g.,
+ API key, bearer token).
+
+### Code
+
+=== "Python"
+ ```python
+ import subprocess
+ from google.adk.agents import LlmAgent
+ from google.adk.models.lite_llm import LiteLlm
+
+ # --- Example Agent using a model hosted on a vLLM endpoint ---
+
+ # Endpoint URL provided by your model deployment
+ api_base_url = "https://your-vllm-endpoint.run.app/v1"
+
+ # Model name as recognized by *your* vLLM endpoint configuration
+ model_name_at_endpoint = "openai/google/gemma-4-31B-it"
+
+ # Simple tool to try
+ def get_weather(location: str) -> str:
+ return f"Location: {location}. Weather: sunny, 76 degrees Fahrenheit, 8 mph wind."
+
+ # Authentication (Example: using gcloud identity token for a Cloud Run deployment)
+ # Adapt this based on your endpoint's security
+ try:
+ gcloud_token = subprocess.check_output(
+ ["gcloud", "auth", "print-identity-token", "-q"]
+ ).decode().strip()
+ auth_headers = {"Authorization": f"Bearer {gcloud_token}"}
+ except Exception as e:
+ print(f"Warning: Could not get gcloud token - {e}.")
+ auth_headers = None # Or handle error appropriately
+
+ root_agent = LlmAgent(
+ model=LiteLlm(
+ model=model_name_at_endpoint,
+ api_base=api_base_url,
+ # Pass authentication headers if needed
+ extra_headers=auth_headers
+ # Alternatively, if endpoint uses an API key:
+ # api_key="YOUR_ENDPOINT_API_KEY",
+ extra_body={
+ "chat_template_kwargs": {
+ "enable_thinking": True # Enable thinking
+ },
+ "skip_special_tokens": False # Should be set to False
+ },
+ ),
+ name="weather_agent",
+ instruction="You are a helpful assistant that can provide current weather.",
+ tools=[get_weather] # Tools!
+ )
+ ```
+
+=== "Java"
+ To use Gemma hosted on vLLM, you must use an OpenAI compatible library.
+ LangChain4j offers an OpenAI dependency that you can add to your `pom.xml`:
+ ```xml
+
+
+ com.google.adk
+ google-adk-langchain4j
+ ${adk.version}
+
+
+
+ dev.langchain4j
+ langchain4j-core
+ ${langchain4j.version}
+
+
+
+ dev.langchain4j
+ langchain4j-open-ai
+ ${langchain4j.version}
+
+ ```
+
+ Create an OpenAI compatible chat model (streaming or non-streaming),
+ wrap it with the `LangChain4j` wrapper,
+ then pass it to the `LlmAgent`:
+ ```java
+ import com.google.adk.agents.LlmAgent;
+ import com.google.adk.tools.Annotations.Schema;
+ import com.google.adk.tools.FunctionTool;
+ import dev.langchain4j.model.chat.StreamingChatModel;
+ import dev.langchain4j.model.openai.OpenAiStreamingChatModel;
+
+ // Endpoint URL provided by your model deployment
+ String apiBaseUrl = "https://your-vllm-endpoint.run.app/v1";
+
+ // Model name as recognized by *your* vLLM endpoint configuration
+ String gemmaModelName = "gg-hf-gg/gemma-4-31b-it";
+
+ // First, define an OpenAI compatible chat model with LangChain4j
+ StreamingChatModel model =
+ OpenAiStreamingChatModel.builder()
+ .modelName(gemmaModelName)
+ // If your endpoint requires an API key
+ // .apiKey("YOUR_ENDPOINT_API_KEY")
+ .baseUrl(apiBaseUrl)
+ .customParameters(
+ Map.of(
+ "skip_special_tokens", false,
+ "chat_template_kwargs", Map.of("enable_thinking", true)
+ )
+ )
+ .build();
+
+ // Configure the agent with the LangChain4j wrapper model
+ LlmAgent weatherAgent = LlmAgent.builder()
+ .model(new LangChain4j(model))
+ .name("weather_agent")
+ .instruction("""
+ You are a helpful assistant that can provide the current weather.
+ """)
+ .tools(FunctionTool.create(this, "getWeather")]
+ .build();
+
+ @Schema(name = "getWeather",
+ description = "Retrieve the weather forecast for a given location")
+ public Map getWeather(
+ @Schema(name = "location",
+ description = "The location for the weather forecast")
+ String location) {
+ return Map.of("forecast", "Location: " + location
+ + ". Weather: sunny, 76 degrees Fahrenheit, 8 mph wind.");
+ }
+ ```
+
+## Build a food tour agent with Gemma 4, ADK, and Google Maps MCP
+This sample shows how to build a personalized food tour agent using Gemma 4, ADK, and the Google Maps MCP server. The agent takes a user’s dish photo or text description, a location, and an optional budget, then recommends places to eat and organizes them into a walking route.
+
+### Prerequisites
+
+- Get an API key in [Google AI Studio](https://aistudio.google.com/app/apikey).
+ Set `GEMINI_API_KEY` environment variable to your Gemini API key.
+- Enable [Google Maps API](https://console.cloud.google.com/maps-api/) on Google Cloud Console.
+- Create a [Google Maps Platform API key](https://console.cloud.google.com/maps-api/credentials).
+ Set `MAPS_API_KEY` environment variable to your API key.
+- Install ADK and configure it in your Python environment
+ or configure the Java dependencies in your Java project.
+
+### Project structure
+```bash
+food_tour_app/
+├── __init__.py
+└── agent.py
+```
+**Full project can be found [here](https://github.com/google/adk-samples/tree/main/python/agents/gemma-food-tour-guide)**
+
+`agent.py`
+```python
+import os
+import dotenv
+from google.adk.agents import LlmAgent
+from google.adk.models import Gemini
+from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
+
+dotenv.load_dotenv()
+
+system_instruction = """
+You are an expert personalized food tour guide.
+Your goal is to build a culinary tour based on the user's inputs: a photo of a dish (or a text description), a location, and a budget.
+
+Follow these 4 rigorous steps:
+1. **Identify the Cuisine/Dish:** Analyze the user's provided description or image URL to determine the primary cuisine or specific dish.
+2. **Find the Best Spots:** Use the `search_places` tool to find highly rated restaurants, stalls, or cafes serving that cuisine/dish in the user's specified location.
+ **CRITICAL RULE FOR PLACES:** `search_places` returns AI-generated place data summaries along with `place_id`, latitude/longitude coordinates, and map links for each place, but may lack a direct, explicit name field. You must carefully associate each described place to its provided `place_id` or `lat_lng`.
+3. **Build the Route:** Use the `compute_routes` tool to structure a walking-optimized route between the selected spots.
+ **CRITICAL ROUTING RULE:** To avoid hallucinating, you MUST provide the `origin` and `destination` using the exact `place_id` string OR `lat_lng` object returned by `search_places`. Do NOT guess or hallucinate an `address` or `place_id` if you do not know the exact name.
+4. **Insider Tips:** Provide specific "order this, skip that" insider tips for each location on the tour.
+
+Structure your response clearly and concisely. If the user provides a budget, ensure your suggestions align with it.
+"""
+
+MAPS_MCP_URL = "https://mapstools.googleapis.com/mcp"
+
+def get_maps_mcp_toolset():
+ dotenv.load_dotenv()
+ maps_api_key = os.getenv("MAPS_API_KEY")
+ if not maps_api_key:
+ print("Warning: MAPS_API_KEY environment variable not found.")
+ maps_api_key = "no_api_found"
+
+ tools = MCPToolset(
+ connection_params=StreamableHTTPConnectionParams(
+ url=MAPS_MCP_URL,
+ headers={
+ "X-Goog-Api-Key": maps_api_key
+ }
+ )
+ )
+ print("Google Maps MCP Toolset configured.")
+ return tools
+
+maps_toolset = get_maps_mcp_toolset()
+
+root_agent = LlmAgent(
+ model=Gemini(model="gemma-4-31b-it"),
+ name="food_tour_agent",
+ instruction=system_instruction,
+ tools=[maps_toolset],
+)
+```
+
+### Environment variables
+Set the required environment variables before running the agent.
+```
+export MAPS_API_KEY="YOUR_GOOGLE_MAPS_API_KEY"
+export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
+```
+
+### Example usage
+To test out the capabilities of the Food Tour Agent, try pasting one of these prompts into the chat:
+
+- *"I want to do a ramen tour in Toronto. My budget is $60 for the day. Give me a walking route for the top 3 spots and tell me what I should order at each."*
+- *"I have this photo of a deep dish pizza [insert image URL]. I want to find the best places for this around Navy Pier in Chicago. Structure a walking tour and tell me what the must-have slice is at each stop."*
+- *"I'm in Downtown Austin looking for an authentic BBQ tour. Let's keep the budget under $100. Build a walking route between 3 highly-rated spots and give me insider tips on the best cuts of meat to get."*
+
+The agent will:
+
+1. Infer the likely cuisine or dish style
+2. Search for relevant places using Google Maps MCP tools
+3. Compute a walking route between selected stops
+4. Return a structured food tour with recommendations and insider tips
diff --git a/docs/agents/models/index.md b/docs/agents/models/index.md
index 8fc3549db1..2858bffa6f 100644
--- a/docs/agents/models/index.md
+++ b/docs/agents/models/index.md
@@ -9,24 +9,30 @@ integrate various Large Language Models (LLMs) into your agents. This section
details how to leverage Gemini and integrate other popular models effectively,
including those hosted externally or running locally.
-ADK primarily uses two mechanisms for model integration:
-
-1. **Direct String / Registry:** For models tightly integrated with Google Cloud,
- such as Gemini models accessed via Google AI Studio or Vertex AI, or models
- hosted on Vertex AI endpoints. You access these models by providing the model name or endpoint resource string and ADK's internal registry
- resolves this string to the appropriate backend client.
-
- * [Gemini models](/adk-docs/agents/models/google-gemini/)
- * [Claude models](/adk-docs/agents/models/anthropic/)
- * [Vertex AI hosted models](/adk-docs/agents/models/vertex/)
-
-2. **Model connectors:** For broader compatibility, especially models
- outside the Google ecosystem or those requiring specific client
- configurations, such as models accessed via Apigee or LiteLLM. You instantiate a specific wrapper class, such as `ApigeeLlm` or
- `LiteLlm`, and pass this object as the `model` parameter
- to your `LlmAgent`.
-
- * [Apigee models](/adk-docs/agents/models/apigee/)
- * [LiteLLM models](/adk-docs/agents/models/litellm/)
- * [Ollama model hosting](/adk-docs/agents/models/ollama/)
- * [vLLM model hosting](/adk-docs/agents/models/vllm/)
+ADK provides several mechanisms for model integration:
+
+1. **Direct String / Registry:** For models tightly integrated with Google
+ Cloud, such as Gemini models accessed via Google AI Studio or Agent Platform,
+ or models hosted on Agent Platform endpoints. You access these models by
+ providing the model name or endpoint resource string and ADK's internal
+ registry resolves this string to the appropriate backend client.
+
+ * [Gemini models](/agents/models/google-gemini/)
+ * [Claude models](/agents/models/anthropic/)
+ * [Agent Platform hosted models](/agents/models/agent-platform/)
+
+2. **Model connectors:** For broader compatibility, especially models outside
+ the Google ecosystem or those requiring specific client configurations, such
+ as models accessed via Apigee or LiteLLM. You instantiate a specific wrapper
+ class, such as `ApigeeLlm` or `LiteLlm`, and pass this object as the `model`
+ parameter to your `LlmAgent`.
+
+ * [Apigee models](/agents/models/apigee/)
+ * [LiteLLM models](/agents/models/litellm/)
+ * [Ollama model hosting](/agents/models/ollama/)
+ * [vLLM model hosting](/agents/models/vllm/)
+ * [LiteRT-LM model hosting](/agents/models/litert-lm/)
+
+3. **[Model routing](/agents/models/routing/):** For dynamically selecting
+ between multiple models at runtime using a router function, with automatic
+ failover on error.
diff --git a/docs/agents/models/litellm.md b/docs/agents/models/litellm.md
index bd97a438e7..17cdc8f990 100644
--- a/docs/agents/models/litellm.md
+++ b/docs/agents/models/litellm.md
@@ -4,11 +4,22 @@
Supported in ADKPython v0.1.0
+??? danger "ADK Python Security Advisory: LiteLLM supply chain compromise"
+
+ Unauthorized code was identified in LiteLLM versions 1.82.7 and 1.82.8 on
+ PyPI on March 24, 2026. If you use ADK Python with the `eval` or
+ `extensions` extras, update to the latest version of ADK Python immediately.
+ If you installed or upgraded LiteLLM during this period, rotate all secrets
+ and credentials. For details and required actions, refer to the [ADK
+ security advisory](https://github.com/google/adk-python/issues/5005) and
+ [LiteLLM's Security Update: Suspected Supply Chain
+ Incident](https://docs.litellm.ai/blog/security-update-march-2026).
+
[LiteLLM](https://docs.litellm.ai/) is a Python library that acts as a
translation layer for models and model hosting services, providing a
standardized, OpenAI-compatible interface to over 100+ LLMs. ADK provides
integration through the LiteLLM library, allowing you to access a vast range of
-LLMs from providers like OpenAI, Anthropic (non-Vertex AI), Cohere, and many
+LLMs from providers like OpenAI, Anthropic (non-Agent Platform), Cohere, and many
others. You can run open-source models locally or self-host them and integrate
them using LiteLLM for operational control, cost savings, privacy, or offline
use cases.
@@ -19,8 +30,8 @@ You can use the LiteLLM library to access remote or locally hosted AI models:
as the `model` parameter of `LlmAgent`.
* **Local model host:** Use the `LiteLlm` wrapper class configured to
point to your local model server. For examples of local model hosting
- solutions, see the [Ollama](/adk-docs/agents/models/ollama/)
- or [vLLM](/adk-docs/agents/models/vllm/) documentation.
+ solutions, see the [Ollama](/agents/models/ollama/)
+ or [vLLM](/agents/models/vllm/) documentation.
??? warning "Windows Encoding with LiteLLM"
@@ -54,7 +65,7 @@ You can use the LiteLLM library to access remote or locally hosted AI models:
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```
- * *Example for Anthropic (non-Vertex AI):*
+ * *Example for Anthropic (non-Agent Platform):*
```shell
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
diff --git a/docs/agents/models/litert-lm.md b/docs/agents/models/litert-lm.md
new file mode 100644
index 0000000000..afeef83744
--- /dev/null
+++ b/docs/agents/models/litert-lm.md
@@ -0,0 +1,101 @@
+# LiteRT-LM model host for ADK agents
+
+
+ Supported in ADKPython v0.1.0
+
+
+[LiteRT-LM](https://github.com/google-ai-edge/LiteRT-LM) is a C++ library to
+efficiently run language models across edge platforms.
+On desktop (Linux, macOS, and Windows), ADK integrates with LiteRT-LM-hosted
+models through the LiteRT-LM server launched by the LiteRT-LM CLI `lit`.
+
+## Get started
+
+LiteRT-LM works with the `Gemini` class. You only have to set the `base_url` and
+`model` parameters.
+
+1. Set `base_url` to the LiteRT-LM server URL, for example: `localhost:8001`.
+2. Set `model` to the LiteRT-LM model name, for example: `gemma3n-e2b`.
+
+```py
+from google.adk.agents import Agent
+from google.adk.models import Gemini
+
+root_agent = Agent(
+ model=Gemini(
+ model="gemma3n-e2b",
+ base_url="http://localhost:8001",
+ ),
+ name="dice_agent",
+ description=(
+ "hello world agent that can roll a die of 8 sides and check prime"
+ " numbers."
+ ),
+ instruction="""
+ You roll dice and answer questions about the outcome of the dice rolls.
+ """,
+ tools=[
+ roll_die,
+ check_prime,
+ ],
+)
+```
+
+Then run the agent as usual:
+
+```bash
+adk web
+```
+
+## Running the LiteRT-LM Server
+
+The LiteRT-LM server is a separate process that serves LiteRT-LM models. It is
+started by the LiteRT-LM CLI tool `lit`.
+
+### Download the `lit` CLI tool
+
+Download the `lit` CLI tool by following these
+[instructions](https://github.com/google-ai-edge/LiteRT-LM?tab=readme-ov-file#desktop-cli-lit)
+in the LiteRT-LM GitHub repository.
+
+### Download a model
+
+Before you start the server, you need to download a model. You'll need a
+*Hugging Face* user access token to download a LiteRT-LM model using `lit`. You
+can get a token for your *Hugging Face* account
+[here](https://huggingface.co/settings/tokens).
+
+To see a list of models available for download, use the `lit list` command:
+
+```bash
+lit list --show_all
+```
+
+Download a model using the `lit pull` command:
+
+```bash
+export HUGGING_FACE_HUB_TOKEN="**your Hugging Face token**"
+lit pull gemma3n-e2b
+```
+
+### Run the server
+
+After downloading a model, start the LiteRT-LM server locally by running the
+following command:
+
+```bash
+lit serve --port 8001
+```
+
+!!! tip "Local Server Port Number"
+
+ You may choose any port number for the LiteRT-LM server as long as it matches the `base_url` you set in the `Gemini` class in your agent code.
+
+### Debugging
+
+To see incoming requests to the LiteRT-LM server and the exact input sent to the
+model, use the `--verbose` flag:
+
+```bash
+lit serve --port 8001 --verbose
+```
diff --git a/docs/agents/models/ollama.md b/docs/agents/models/ollama.md
index 89b3d7bee0..017560683f 100644
--- a/docs/agents/models/ollama.md
+++ b/docs/agents/models/ollama.md
@@ -6,7 +6,7 @@
[Ollama](https://ollama.com/) is a tool that allows you to host and run
open-source models locally. ADK integrates with Ollama-hosted models through the
-[LiteLLM](/adk-docs/agents/models/litellm/) model connector library.
+[LiteLLM](/agents/models/litellm/) model connector library.
## Get started
diff --git a/docs/agents/models/routing.md b/docs/agents/models/routing.md
new file mode 100644
index 0000000000..4c51847bf6
--- /dev/null
+++ b/docs/agents/models/routing.md
@@ -0,0 +1,64 @@
+# Route between models
+
+
+ Supported in ADKTypeScript v1.0.0Experimental
+
+
+!!! example "Experimental"
+
+ Model routing is experimental and may change in future releases. We welcome
+ your
+ [feedback](https://github.com/google/adk-js/issues/new?template=feature_request.md)!
+
+An `LlmAgent` uses a single model by default. When you need to dynamically
+select between different models for each request, you can define a routing
+function that chooses which model to use. `RoutedLlm` provides this capability,
+enabling model fallback on error, A/B testing between models, and auto-routing
+by input complexity. If the selected model fails before producing any output,
+the routing function is called again with error context so it can select a
+different model.
+
+Pass a `RoutedLlm` as an `LlmAgent`'s `model` parameter. Use `RoutedLlm` when
+only the model varies between routes. If you also need to switch instructions,
+tools, or sub-agents, use [`RoutedAgent`](../routing.md) instead.
+
+## How routing works
+
+The `LlmRouter` function receives the map of available models and the current
+`LlmRequest`, and returns the key of the model to use:
+
+=== "TypeScript"
+
+ ```typescript
+ type LlmRouter = (
+ models: Readonly>,
+ request: LlmRequest,
+ errorContext?: { failedKeys: ReadonlySet; lastError: unknown },
+ ) => Promise | string | undefined;
+ ```
+
+The `models` parameter accepts either a `Record` with explicit
+keys, or an array of `BaseLlm` instances. If an array is provided, each model's
+name is used as its key.
+
+Failover follows the same rules as
+[`RoutedAgent`](../routing.md#how-routing-works): the router is re-called with
+`errorContext` only if the selected model fails before yielding any response.
+After yielding, errors propagate without retry. The router can return
+`undefined` to stop retrying and propagate the last error.
+
+**Live connections:** `RoutedLlm.connect()` selects the model at connection
+time. Once a live connection is established, the model cannot be switched
+mid-stream.
+
+## Basic usage
+
+The following example creates a `RoutedLlm` that tries a primary model first and
+falls back to a secondary model if the primary fails. The router checks
+`errorContext.failedKeys` to avoid re-selecting the failed model:
+
+=== "TypeScript"
+
+ ```typescript
+ --8<-- "examples/typescript/snippets/agents/models/routing/basic-usage.ts:full"
+ ```
diff --git a/docs/agents/models/vllm.md b/docs/agents/models/vllm.md
index a43c63e23b..0a8c62cce8 100644
--- a/docs/agents/models/vllm.md
+++ b/docs/agents/models/vllm.md
@@ -6,7 +6,7 @@
Tools such as [vLLM](https://github.com/vllm-project/vllm) allow you to host
models efficiently and serve them as an OpenAI-compatible API endpoint. You can
-use vLLM models through the [LiteLLM](/adk-docs/agents/models/litellm/) library
+use vLLM models through the [LiteLLM](/agents/models/litellm/) library
for Python.
## Setup
@@ -30,13 +30,13 @@ import subprocess
from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
-# --- Example Agent using a model hosted on a vLLM endpoint ---
+# --- Example Agent using a Gemma 4 model hosted on a vLLM endpoint ---
# Endpoint URL provided by your vLLM deployment
api_base_url = "https://your-vllm-endpoint.run.app/v1"
# Model name as recognized by *your* vLLM endpoint configuration
-model_name_at_endpoint = "hosted_vllm/google/gemma-3-4b-it" # Example from vllm_test.py
+model_name_at_endpoint = "hosted_vllm/google/gemma-4-E4B-it" # Example from vllm_test.py
# Authentication (Example: using gcloud identity token for a Cloud Run deployment)
# Adapt this based on your endpoint's security
@@ -53,8 +53,15 @@ agent_vllm = LlmAgent(
model=LiteLlm(
model=model_name_at_endpoint,
api_base=api_base_url,
+ # This extra_body values specific to Gemma 4.
+ extra_body={
+ "chat_template_kwargs": {
+ "enable_thinking": True # Enable thinking
+ },
+ "skip_special_tokens": False # Should be set to False
+ },
# Pass authentication headers if needed
- extra_headers=auth_headers
+ extra_headers=auth_headers,
# Alternatively, if endpoint uses an API key:
# api_key="YOUR_ENDPOINT_API_KEY"
),
diff --git a/docs/agents/multi-agents.md b/docs/agents/multi-agents.md
index 7bc29287f1..1e7fe13b1c 100644
--- a/docs/agents/multi-agents.md
+++ b/docs/agents/multi-agents.md
@@ -39,14 +39,14 @@ The foundation for structuring multi-agent systems is the parent-child relations
# Define individual agents
- greeter = LlmAgent(name="Greeter", model="gemini-2.0-flash")
+ greeter = LlmAgent(name="Greeter", model="gemini-flash-latest")
task_doer = BaseAgent(name="TaskExecutor") # Custom non-LLM agent
# Create parent agent and assign children via sub_agents
coordinator = LlmAgent(
name="Coordinator",
- model="gemini-2.0-flash",
+ model="gemini-flash-latest",
description="I coordinate greetings and tasks.",
sub_agents=[ # Assign sub_agents here
greeter,
@@ -84,13 +84,13 @@ The foundation for structuring multi-agent systems is the parent-child relations
}
// Define individual agents
- const greeter = new LlmAgent({name: 'Greeter', model: 'gemini-2.5-flash'});
+ const greeter = new LlmAgent({name: 'Greeter', model: 'gemini-flash-latest'});
const taskDoer = new TaskExecutorAgent({name: 'TaskExecutor'}); // Custom non-LLM agent
// Create parent agent and assign children via subAgents
const coordinator = new LlmAgent({
name: 'Coordinator',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
description: 'I coordinate greetings and tasks.',
subAgents: [ // Assign subAgents here
greeter,
@@ -123,14 +123,14 @@ The foundation for structuring multi-agent systems is the parent-child relations
// Define individual agents
- LlmAgent greeter = LlmAgent.builder().name("Greeter").model("gemini-2.0-flash").build();
+ LlmAgent greeter = LlmAgent.builder().name("Greeter").model("gemini-flash-latest").build();
SequentialAgent taskDoer = SequentialAgent.builder().name("TaskExecutor").subAgents(...).build(); // Sequential Agent
// Create parent agent and assign sub_agents
LlmAgent coordinator = LlmAgent.builder()
.name("Coordinator")
- .model("gemini-2.0-flash")
+ .model("gemini-flash-latest")
.description("I coordinate greetings and tasks")
.subAgents(greeter, taskDoer) // Assign sub_agents here
.build();
@@ -397,7 +397,7 @@ Agents within a system often need to exchange data or trigger actions in one ano
#### a) Shared Session State (`session.state`)
-The most fundamental way for agents operating within the same invocation (and thus sharing the same [`Session`](/adk-docs/sessions/session/) object via the `InvocationContext`) to communicate passively.
+The most fundamental way for agents operating within the same invocation (and thus sharing the same [`Session`](/sessions/session/) object via the `InvocationContext`) to communicate passively.
* **Mechanism:** One agent (or its tool/callback) writes a value (`context.state['data_key'] = processed_data`), and a subsequent agent reads it (`data = context.state.get('data_key')`). State changes are tracked via [`CallbackContext`](../callbacks/index.md).
* **Convenience:** The `output_key` property on [`LlmAgent`](llm-agents.md) automatically saves the agent's final response text (or structured output) to the specified state key.
@@ -498,7 +498,7 @@ Leverages an [`LlmAgent`](llm-agents.md)'s understanding to dynamically route ta
coordinator = LlmAgent(
name="Coordinator",
- model="gemini-2.0-flash",
+ model="gemini-flash-latest",
instruction="You are an assistant. Delegate booking tasks to Booker and info requests to Info.",
description="Main coordinator.",
# AutoFlow is typically used implicitly here
@@ -520,7 +520,7 @@ Leverages an [`LlmAgent`](llm-agents.md)'s understanding to dynamically route ta
const coordinator = new LlmAgent({
name: 'Coordinator',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
instruction: 'You are an assistant. Delegate booking tasks to Booker and info requests to Info.',
description: 'Main coordinator.',
// AutoFlow is typically used implicitly here
@@ -563,7 +563,7 @@ Leverages an [`LlmAgent`](llm-agents.md)'s understanding to dynamically route ta
// Define the coordinator agent
LlmAgent coordinator = LlmAgent.builder()
.name("Coordinator")
- .model("gemini-2.0-flash") // Or your desired model
+ .model("gemini-flash-latest") // Or your desired model
.instruction("You are an assistant. Delegate booking tasks to Booker and info requests to Info.")
.description("Main coordinator.")
// AutoFlow will be used by default (implicitly) because subAgents are present
@@ -578,8 +578,8 @@ Leverages an [`LlmAgent`](llm-agents.md)'s understanding to dynamically route ta
#### c) Explicit Invocation (`AgentTool`)
-Allows an [`LlmAgent`](llm-agents.md) to treat another `BaseAgent` instance as a callable function or
-[Tool](/adk-docs/tools-custom/).
+Allows an [`LlmAgent`](llm-agents.md) to treat another `BaseAgent` instance as a callable function or
+[Tool](/tools-custom/).
* **Mechanism:** Wrap the target agent instance in `AgentTool` and include it in the parent `LlmAgent`'s `tools` list. `AgentTool` generates a corresponding function declaration for the LLM.
* **Handling:** When the parent LLM generates a function call targeting the `AgentTool`, the framework executes `AgentTool.run_async`. This method runs the target agent, captures its final response, forwards any state/artifact changes back to the parent's context, and returns the response as the tool's result.
@@ -614,7 +614,7 @@ Allows an [`LlmAgent`](llm-agents.md) to treat another `BaseAgent` instance as a
# Parent agent uses the AgentTool
artist_agent = LlmAgent(
name="Artist",
- model="gemini-2.0-flash",
+ model="gemini-flash-latest",
instruction="Create a prompt and use the ImageGen tool to generate the image.",
tools=[image_tool] # Include the AgentTool
)
@@ -656,7 +656,7 @@ Allows an [`LlmAgent`](llm-agents.md) to treat another `BaseAgent` instance as a
// Parent agent uses the AgentTool
const artistAgent = new LlmAgent({
name: 'Artist',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
instruction: 'Create a prompt and use the ImageGen tool to generate the image.',
tools: [imageTool] // Include the AgentTool
});
@@ -733,7 +733,7 @@ Allows an [`LlmAgent`](llm-agents.md) to treat another `BaseAgent` instance as a
// Parent agent uses the AgentTool
LlmAgent artistAgent = LlmAgent.builder()
.name("Artist")
- .model("gemini-2.0-flash")
+ .model("gemini-flash-latest")
.instruction(
"You are an artist. Create a detailed prompt for an image and then " +
"use the 'ImageGen' tool to generate the image. " +
@@ -779,7 +779,7 @@ By combining ADK's composition primitives, you can implement various established
coordinator = LlmAgent(
name="HelpDeskCoordinator",
- model="gemini-2.0-flash",
+ model="gemini-flash-latest",
instruction="Route user requests: Use Billing agent for payment issues, Support agent for technical problems.",
description="Main help desk router.",
# allow_transfer=True is often implicit with sub_agents in AutoFlow
@@ -800,7 +800,7 @@ By combining ADK's composition primitives, you can implement various established
const coordinator = new LlmAgent({
name: 'HelpDeskCoordinator',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
instruction: 'Route user requests: Use Billing agent for payment issues, Support agent for technical problems.',
description: 'Main help desk router.',
// allowTransfer=true is often implicit with subAgents in AutoFlow
@@ -839,7 +839,7 @@ By combining ADK's composition primitives, you can implement various established
LlmAgent coordinator = LlmAgent.builder()
.name("HelpDeskCoordinator")
- .model("gemini-2.0-flash")
+ .model("gemini-flash-latest")
.instruction("Route user requests: Use Billing agent for payment issues, Support agent for technical problems.")
.description("Main help desk router.")
.subAgents(billingAgent, supportAgent)
@@ -1093,7 +1093,7 @@ By combining ADK's composition primitives, you can implement various established
# Mid-level agent combining tools
research_assistant = LlmAgent(
name="ResearchAssistant",
- model="gemini-2.0-flash",
+ model="gemini-flash-latest",
description="Finds and summarizes information on a topic.",
tools=[agent_tool.AgentTool(agent=web_searcher), agent_tool.AgentTool(agent=summarizer)]
)
@@ -1102,7 +1102,7 @@ By combining ADK's composition primitives, you can implement various established
# High-level agent delegating research
report_writer = LlmAgent(
name="ReportWriter",
- model="gemini-2.0-flash",
+ model="gemini-flash-latest",
instruction="Write a report on topic X. Use the ResearchAssistant to gather information.",
tools=[agent_tool.AgentTool(agent=research_assistant)]
# Alternatively, could use LLM Transfer if research_assistant is a sub_agent
@@ -1126,7 +1126,7 @@ By combining ADK's composition primitives, you can implement various established
// Mid-level agent combining tools
const researchAssistant = new LlmAgent({
name: 'ResearchAssistant',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
description: 'Finds and summarizes information on a topic.',
tools: [new AgentTool({agent: webSearcher}), new AgentTool({agent: summarizer})]
});
@@ -1134,7 +1134,7 @@ By combining ADK's composition primitives, you can implement various established
// High-level agent delegating research
const reportWriter = new LlmAgent({
name: 'ReportWriter',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
instruction: 'Write a report on topic X. Use the ResearchAssistant to gather information.',
tools: [new AgentTool({agent: researchAssistant})]
// Alternatively, could use LLM Transfer if researchAssistant is a subAgent
@@ -1181,7 +1181,7 @@ By combining ADK's composition primitives, you can implement various established
// Mid-level agent combining tools
LlmAgent researchAssistant = LlmAgent.builder()
.name("ResearchAssistant")
- .model("gemini-2.0-flash")
+ .model("gemini-flash-latest")
.description("Finds and summarizes information on a topic.")
.tools(AgentTool.create(webSearcher), AgentTool.create(summarizer))
.build();
@@ -1190,7 +1190,7 @@ By combining ADK's composition primitives, you can implement various established
// High-level agent delegating research
LlmAgent reportWriter = LlmAgent.builder()
.name("ReportWriter")
- .model("gemini-2.0-flash")
+ .model("gemini-flash-latest")
.instruction("Write a report on topic X. Use the ResearchAssistant to gather information.")
.tools(AgentTool.create(researchAssistant))
// Alternatively, could use LLM Transfer if research_assistant is a subAgent
@@ -1696,7 +1696,7 @@ A conceptual example of using a `CustomPolicyEngine` to require user confirmatio
```typescript
const rootAgent = new LlmAgent({
name: 'weather_time_agent',
- model: 'gemini-2.5-flash',
+ model: 'gemini-flash-latest',
description:
'Agent to answer questions about the time and weather in a city.',
instruction:
diff --git a/docs/agents/routing.md b/docs/agents/routing.md
new file mode 100644
index 0000000000..67f8e3273c
--- /dev/null
+++ b/docs/agents/routing.md
@@ -0,0 +1,126 @@
+# Route between agents
+
+
+ Supported in ADKTypeScript v1.0.0Experimental
+
+
+!!! example "Experimental"
+
+ Agent routing is experimental and may change in future releases. We welcome
+ your
+ [feedback](https://github.com/google/adk-js/issues/new?template=feature_request.md)!
+
+When building agents for different tasks, you can define a routing function that
+selects which one handles each invocation at runtime. `RoutedAgent` provides
+this capability, enabling agent fallback on error, A/B testing, planning modes,
+and auto-routing by input complexity. If the selected agent fails before
+producing any output, the routing function is called again with error context so
+it can select a fallback.
+
+`RoutedAgent` is different from [workflow agents](workflow-agents/index.md) like
+`SequentialAgent` or `ParallelAgent`, which orchestrate multiple agents in a
+fixed pattern, and from [LLM-driven
+delegation](multi-agents.md#b-llm-driven-delegation-agent-transfer), where the
+LLM decides which agent to hand off to. With `RoutedAgent`, you write an
+explicit routing function that selects **one** agent per invocation. For
+model-level routing, see [Model routing](models/routing.md).
+
+## How routing works
+
+Both `RoutedAgent` and [`RoutedLlm`](models/routing.md) are powered by a shared
+routing utility that handles selection and failover.
+
+The router function receives the map of available agents and the current
+context, and returns the key of the agent to run. It can be synchronous or
+async:
+
+=== "TypeScript"
+
+ ```typescript
+ type AgentRouter = (
+ agents: Readonly>,
+ context: InvocationContext,
+ errorContext?: { failedKeys: ReadonlySet; lastError: unknown },
+ ) => Promise | string | undefined;
+ ```
+
+**The `agents` parameter** accepts either a `Record` with
+explicit keys, or an array of agents. If an array is provided, each agent's
+`name` property is used as its key.
+
+**Failover behavior:**
+
+- The router is first called without `errorContext` to make the initial
+ selection.
+- If the selected agent throws an error **before yielding any events**, the
+ router is called again with `errorContext` containing `failedKeys` and
+ `lastError`.
+- If the selected agent throws an error **after yielding events**, the error
+ propagates directly without retry, because partial results have already been
+ emitted.
+- A key that has already been tried cannot be re-selected. If the router returns
+ a previously failed key, the error propagates.
+- If the router returns `undefined`, routing stops and the last error is thrown.
+
+## Basic usage
+
+Create multiple agents, define a router function that returns a key, and wrap
+them in a `RoutedAgent`. The following example routes between two agents based
+on an external configuration value that can change between invocations:
+
+=== "TypeScript"
+
+ ```typescript
+ --8<-- "examples/typescript/snippets/agents/routing/basic-usage.ts:full"
+ ```
+
+Change `config.selectedAgent` to `'agent_b'` before the next invocation to
+route to a different agent.
+
+## Fallback on error
+
+When an agent fails, the router is called again with `errorContext` so it can
+select a fallback. Failover only applies if the agent fails before yielding any
+events (see [How routing works](#how-routing-works)). The following example
+checks `errorContext.failedKeys` to avoid re-selecting the failed agent:
+
+=== "TypeScript"
+
+ ```typescript
+ --8<-- "examples/typescript/snippets/agents/routing/fallback.ts:config"
+ ```
+
+## Planning mode
+
+A router can read any external state to select between agents with different
+instructions, models, and tools. This lets you implement a planning mode where
+the agent switches behavior dynamically. For example, a basic agent might have
+read and write tools, while a planning agent is restricted to read-only access
+and uses a more powerful model for analysis.
+
+The following example shows a different `RoutedAgent` configuration. See [basic
+usage](#basic-usage) for the full runner setup.
+
+=== "TypeScript"
+
+ ```typescript
+ --8<-- "examples/typescript/snippets/agents/routing/planning-mode.ts:config"
+ ```
+
+Set `planningMode = true` before an invocation to route to the planning agent
+with its restricted tool set and different instructions.
+
+## Auto-routing by complexity
+
+The router function can call a lightweight classifier model to categorize input
+and route to different agents accordingly. Because the router can be async, you
+can make LLM calls inside it before selecting an agent.
+
+The following example shows a different `RoutedAgent` configuration. See [basic
+usage](#basic-usage) for the full runner setup.
+
+=== "TypeScript"
+
+ ```typescript
+ --8<-- "examples/typescript/snippets/agents/routing/auto-routing.ts:config"
+ ```
diff --git a/docs/api-reference/cli/_sources/index.rst.txt b/docs/api-reference/cli/_sources/index.rst.txt
index 8edaf9d90d..99a05d1f5a 100644
--- a/docs/api-reference/cli/_sources/index.rst.txt
+++ b/docs/api-reference/cli/_sources/index.rst.txt
@@ -1,7 +1,7 @@
ADK CLI documentation
=====================
-This page contains the auto-generated command-line reference for ADK 1.25.0.
+This page contains the auto-generated command-line reference for ADK 1.32.0.
.. contents::
:local:
diff --git a/docs/api-reference/cli/_static/documentation_options.js b/docs/api-reference/cli/_static/documentation_options.js
index 1077ce70c0..255a4578a8 100644
--- a/docs/api-reference/cli/_static/documentation_options.js
+++ b/docs/api-reference/cli/_static/documentation_options.js
@@ -1,5 +1,5 @@
const DOCUMENTATION_OPTIONS = {
- VERSION: '1.25.0',
+ VERSION: '1.32.0',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',
diff --git a/docs/api-reference/cli/genindex.html b/docs/api-reference/cli/genindex.html
index e7a6eed88f..ee7ce0275d 100644
--- a/docs/api-reference/cli/genindex.html
+++ b/docs/api-reference/cli/genindex.html
@@ -4,11 +4,11 @@
- Index — ADK CLI 1.25.0 documentation
+ Index — ADK CLI 1.32.0 documentation
-
+
@@ -48,6 +48,7 @@
Optional. Deploy ADK Web UI if set. (default: deploy ADK API server only)
+
Optional. Deploy ADK Web UI if set. (default: deploy ADK API server only). WARNING: The web UI is for development and testing only — do not use in production.
Optional. Comma-separated list of trigger sources to enable (e.g., ‘pubsub,eventarc’). Registers /trigger/* endpoints for batch and event-driven agent invocations.
Optional. Deploy ADK Web UI if set. (default: deploy ADK API server only)
+
Optional. Deploy ADK Web UI if set. (default: deploy ADK API server only). WARNING: The web UI is for development and testing only — do not use in production.
Optional. The Kubernetes Service type for the deployed agent. ClusterIP (default) keeps the service cluster-internal; use LoadBalancer to expose a public IP.
Optional. Comma-separated list of trigger sources to enable (e.g., ‘pubsub,eventarc’). Registers /trigger/* endpoints for batch and event-driven agent invocations.
Generates eval cases dynamically and adds them to the given eval set.
+
Uses Vertex AI Eval SDK to generate conversation scenarios based on an
+Agent’s info and definitions. It will automatically create the empty eval_set
+if it has not been created in advance.
+
+
Args:
agent_module_file_path: The path to the agent module file.
+eval_set_id: The id of the eval set to generate cases for.
+user_simulation_config_file: The path to the user simulation config file.
+eval_storage_uri: The eval storage uri.
+log_level: The log level.
Optimizes the root agent instructions using the GEPA optimizer.
+
AGENT_MODULE_FILE_PATH: The path to the __init__.py file that contains a
+module by the name “agent”. “agent” module contains a root_agent.
+
SAMPLER_CONFIG_FILE_PATH: The path to the config for the LocalEvalSampler,
+which contains the eval config and the eval sets to use for training and
+validation during optimization.
+
OPTIMIZER_CONFIG_FILE_PATH: Optional. The path to the config for the
+GEPARootAgentPromptOptimizer. If not provided, the default config will be
+used.
+
PRINT_DETAILED_RESULTS: Optional. Enables printing detailed results exposed by
+the GEPA optimizer to the console.
Optional. Comma-separated list of trigger sources to enable (e.g., ‘pubsub,eventarc’). Registers /apps/{app_name}/trigger/* endpoints for batch and event-driven agent invocations.
Performs a topological search on the dependency graph to find the ordered list of agents that
+must execute to produce a goal output, given a set of initial preconditions (state keys already
+available).
Wraps a real HTTP response to expose the methods needed by the GenAI SDK.
+
Transforms AgentMetadata into a dependency graph where:
+
+
+ Each output key maps to the agent that produces it
+ Each output key maps to the input keys (dependencies) required to produce it
+
Utility class for capturing and reporting telemetry data within the ADK. This class provides
- methods to trace various aspects of the agent's execution, including tool calls, tool responses,
- LLM interactions, and data handling. It leverages OpenTelemetry for tracing and logging for
- detailed information. These traces can then be exported through the ADK Dev Server UI.
+methods to trace various aspects of the agent's execution, including tool calls, tool responses,
+LLM interactions, and data handling. It leverages OpenTelemetry for tracing and logging for
+detailed information. These traces can then be exported through the ADK Dev Server UI.
public staticvoidsetTracerForTesting(io.opentelemetry.api.trace.Tracer tracer)
+
Sets the OpenTelemetry instance to be used for tracing. This is for testing purposes only.
+
+
+
+
traceToolCall
@@ -241,6 +257,40 @@
getTracer
+
+
+
traceFlowable
+
+
public static<T>
+io.reactivex.rxjava3.core.Flowable<T>traceFlowable(io.opentelemetry.context.Context spanContext,
+ io.opentelemetry.api.trace.Span span,
+ Supplier<io.reactivex.rxjava3.core.Flowable<T>> flowableSupplier)
+
Executes a Flowable with an OpenTelemetry Scope active for its entire lifecycle.
+
+
This helper manages the OpenTelemetry Scope lifecycle for RxJava Flowables to ensure proper
+context propagation across async boundaries. The scope remains active from when the Flowable is
+returned through all operators until stream completion (onComplete, onError, or cancel).
+
+
Why not try-with-resources? RxJava Flowables execute lazily - operators run at
+subscription time, not at chain construction time. Using try-with-resources would close the
+scope before the Flowable subscribes, causing Context.current() to return ROOT in nested
+operations and breaking parent-child span relationships (fragmenting traces).
+
+
The scope is properly closed via doFinally when the stream terminates, ensuring no resource
+leaks regardless of completion mode (success, error, or cancellation).
+
+
Type Parameters:
+
T - The type of items emitted by the Flowable
+
Parameters:
+
spanContext - The context containing the span to activate
+
span - The span to end when the stream completes
+
flowableSupplier - Supplier that creates the Flowable to execute with active scope
+
Returns:
+
Flowable with OpenTelemetry scope lifecycle management
Runner.Builderinstead.