diff --git a/.gitignore b/.gitignore index 22e85e2d8..1af86580a 100644 --- a/.gitignore +++ b/.gitignore @@ -134,6 +134,7 @@ venv/ ENV/ env.bak/ venv.bak/ +***/.env # Spyder project settings .spyderproject @@ -183,3 +184,6 @@ docs/site # Claude Code .claude + +# Bash files +***/*.sh diff --git a/docs/assets/adk-run.png b/docs/assets/adk-run.png index ef5a2c6d4..a6c0a4a5f 100644 Binary files a/docs/assets/adk-run.png and b/docs/assets/adk-run.png differ diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 2b3dc77a6..5893eeede 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -1,58 +1,23 @@ -# Get Started +# Get started -Agent Development Kit (ADK) is designed to empower developers -to build, manage, evaluate and deploy AI-powered agents. It provides a robust -and flexible environment for creating both conversational and non-conversational -agents, capable of handling complex tasks and workflows. +Agent Development Kit (ADK) is designed to empower developers to quickly build, +manage, evaluate and deploy AI-powered agents. These quick start guides get you +set up and running a simple agent in less than 20 minutes.
-- :material-console-line: **Installation** +- :fontawesome-brands-python:{ .lg .middle } **Python Quickstart** --- + Create your first Python ADK agent in minutes. - Install `google-adk` for Python or Java and get up and running in minutes. + [:octicons-arrow-right-24: Start with Python](/adk-docs/get-started/python)
- [:octicons-arrow-right-24: More information](installation.md) - -- :material-console-line: **Quickstart** - - --- - - Create your first ADK agent with tools in minutes. - - [:octicons-arrow-right-24: More information](quickstart.md) - -- :material-console-line: **Quickstart (streaming)** - - --- - - Create your first streaming ADK agent. - - [:octicons-arrow-right-24: More information](streaming/quickstart-streaming.md) - -- :material-console-line: **Tutorial** +- :fontawesome-brands-java:{ .lg .middle } **Java Quickstart** --- + Create your first Java ADK agent in minutes. - Create your first ADK multi-agent. - - [:octicons-arrow-right-24: More information](../tutorials/index.md) - -- :material-rocket-launch-outline: **Discover sample agents** - - --- - - Discover sample agents for retail, travel, customer service, and more! - - [:octicons-arrow-right-24: Discover adk-samples](https://github.com/google/adk-samples){:target="_blank"} - -- :material-graph: **About** - - --- - - Learn about the key components of building and deploying ADK agents. - - [:octicons-arrow-right-24: More information](about.md) + [:octicons-arrow-right-24: Start with Java](/adk-docs/get-started/java.md)
diff --git a/docs/get-started/java.md b/docs/get-started/java.md new file mode 100644 index 000000000..b192cb1df --- /dev/null +++ b/docs/get-started/java.md @@ -0,0 +1,258 @@ +# Java Quickstart for ADK + +This guide shows you how to get up and running with Agent Development Kit +for Java. Before you start, make sure you have the following installed: + +* Java 17 or later +* Maven 3.9 or later + +## Create an agent project + +Create an agent project with the following files and directory structure: + +```console +my_agent/ + src/main/java/com/example/agent/ + HelloTimeAgent.java # main agent code + pom.xml # project configuration + .env # API keys or project IDs +``` + +??? tip "Create this project structure using the command line" + + === "Windows" + + ```console + mkdir my_agent\src\main\java\com\example\agent + type nul > my_agent\src\main\java\com\example\agent\HelloTimeAgent.java + type nul > my_agent\pom.xml + type nul > my_agent\.env + ``` + + === "MacOS / Linux" + + ```bash + mkdir -p my_agent/src/main/java/com/example/agent && \ + touch my_agent/src/main/java/com/example/agent/HelloTimeAgent.java \ + touch my_agent/pom.xml my_agent/.env + ``` + +### Define the agent code + +Create the code for a basic agent, including a simple implementation of an ADK +[Function Tool](/adk-docs/tools/function-tools/), called `getCurrentTime()`. +Add the following code to the `HelloTimeAgent.java` file in your project +directory: + +```java title="my_agent/src/main/java/com/example/agent/HelloTimeAgent.java" +package com.example.agent; + +import com.google.adk.agents.BaseAgent; +import com.google.adk.agents.LlmAgent; +import com.google.adk.tools.Annotations.Schema; +import com.google.adk.tools.FunctionTool; + +import java.util.Map; + +public class HelloTimeAgent { + + public static BaseAgent ROOT_AGENT = initAgent(); + + private static BaseAgent initAgent() { + return LlmAgent.builder() + .name("hello-time-agent") + .description("Tells the current time in a specified city") + .instruction(""" + You are a helpful assistant that tells the current time in a city. + Use the 'getCurrentTime' tool for this purpose. + """) + .model("gemini-2.5-flash") + .tools(FunctionTool.create(HelloTimeAgent.class, "getCurrentTime")) + .build(); + } + + /** Mock tool implementation */ + @Schema(description = "Get the current time for a given city") + public static Map getCurrentTime( + @Schema(name = "city", description = "Name of the city to get the time for") String city) { + return Map.of( + "city", city, + "forecast", "The time is 10:30am." + ); + } +} +``` + +### Configure project and dependencies + +An ADK agent project requires this dependency in your +`pom.xml` project file: + +```xml title="my_agent/pom.xml (partial)" + + + com.google.adk + adk-core + 0.3.0 + + +``` + +Update the `pom.xml` project file to include this dependency and +addtional settings with the following configuration code: + +??? info "Complete `pom.xml` configuration for project" + The following code shows a complete `pom.xml` configuration for + this project: + + ```xml title="my_agent/pom.xml" + + + 4.0.0 + + com.example.agent + adk-agents + 1.0-SNAPSHOT + + + + 17 + 17 + UTF-8 + + + + + + com.google.adk + google-adk + 0.3.0 + + + + com.google.adk + google-adk-dev + 0.3.0 + + + + + ``` + +### Set your API key + +This project uses the Gemini API, which requires an API key. If you +don't already have Gemini API key, create a key in Google AI Studio on the +[API Keys](https://aistudio.google.com/app/apikey) page. + +In a terminal window, write your API key into your `.env` file of your project +to set environment variables: + +=== "Windows" + + ```console title="Update: my_agent/.env" + echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env + ``` + +=== "MacOS / Linux" + + ```bash title="Update: my_agent/.env" + echo 'export GOOGLE_API_KEY="YOUR_API_KEY"' > .env + ``` + +### Create an agent command-line interface + +For convenience, create a `AgentCliRunner.java` class to allow you to run +and interact with `HelloTimeAgent` from the command line. This code shows +how to create a `RunConfig` object to run the agent and a `Session` object +to interact with the running agent. + +```java title="my_agent/src/main/java/com/example/agent/AgentCliRunner.java" +package com.example.agent; + +import com.google.adk.agents.RunConfig; +import com.google.adk.events.Event; +import com.google.adk.runner.InMemoryRunner; +import com.google.adk.sessions.Session; +import com.google.genai.types.Content; +import com.google.genai.types.Part; +import io.reactivex.rxjava3.core.Flowable; +import java.util.Scanner; + +import static java.nio.charset.StandardCharsets.UTF_8; + +public class AgentCliRunner { + + public static void main(String[] args) { + RunConfig runConfig = RunConfig.builder().build(); + InMemoryRunner runner = new InMemoryRunner(HelloTimeAgent.ROOT_AGENT); + + Session session = runner + .sessionService() + .createSession(runner.appName(), "user1234") + .blockingGet(); + + try (Scanner scanner = new Scanner(System.in, UTF_8)) { + while (true) { + System.out.print("\nYou > "); + String userInput = scanner.nextLine(); + if ("quit".equalsIgnoreCase(userInput)) { + break; + } + + Content userMsg = Content.fromParts(Part.fromText(userInput)); + Flowable events = runner.runAsync(session.userId(), session.id(), userMsg, runConfig); + + System.out.print("\nAgent > "); + events.blockingForEach(event -> { + if (event.finalResponse()) { + System.out.println(event.stringifyContent()); + } + }); + } + } + } +} +``` + +## Run your agent + +You can run your ADK agent using the interactive command-line interface +`AgentCliRunner` class you defined or the ADK web user interface provided by +the ADK using the `AdkWebServer` class. Both these options allow you to test and +interact with your agent. + +### Run with command-line interface + +Run your agent with the command-line interface `AgentCliRunner` class +using the following Maven command: + +```console +mvn compile exec:java -Dexec.mainClass="com.example.agent.AgentCliRunner" +``` + +![adk-run.png](/adk-docs/assets/adk-run.png) + +### Run with web interface + +Run your agent with the ADK web interface using the following maven command: + +```console +mvn compile exec:java -Dexec.mainClass="com.google.adk.web.AdkWebServer" \ + -Dexec.args="--adk.agents.source-dir=src/main/java/com/example/agent --server.port=8080" +``` + +This command starts a web server with a chat interface for your agent. You can +access the web interface at (http://localhost:8080). Select your agent at the +upper right corner and type a request. + +![adk-web-dev-ui-chat.png](/adk-docs/assets/adk-web-dev-ui-chat.png) + +## Next: Build your agent + +Now that you have ADK installed and your first agent running, try building +your own agent with our build guides: + +* [Build your agent](/adk-docs/tutorials/) diff --git a/docs/get-started/python.md b/docs/get-started/python.md new file mode 100644 index 000000000..6717aa4ab --- /dev/null +++ b/docs/get-started/python.md @@ -0,0 +1,148 @@ +# Python Quickstart for ADK + +This guide shows you how to get up and running with Agent Development Kit +(ADK) for Python. Before you start, make sure you have the following installed: + +* Python 3.9 or later +* `pip` for installing packages + +## Installation + +Install ADK by running the following command: + +```shell +pip install google-adk +``` + +??? tip "Recommended: create and activate a Python virtual environment" + + Create a Python virtual environment: + + ```shell + python -m venv .venv + ``` + + Activate the Python virtual environment: + + === "Windows CMD" + + ```console + .venv\Scripts\activate.bat + ``` + + === "Windows Powershell" + + ```console + .venv\Scripts\Activate.ps1 + ``` + + === "MacOS / Linux" + + ```bash + source .venv/bin/activate + ``` + +## Create an agent project + +Run the `adk create` command to start a new agent project. + +```shell +adk create my_agent +``` + +### Explore the agent project + +The created agent project has the following structure, with the `agent.py` +file containing the main control code for the agent. + +```shell +my_agent/ + agent.py # main agent code + .env # API keys or project IDs + __init__.py +``` + +## Update your agent project + +The `agent.py` file contains a `root_agent` definition which is the only +required element of an ADK agent. You can also define tools for the agent to +use. Update the generated `agent.py` code to include a `get_current_time` tool +for use by the agent, as shown in the following code: + +```python +from google.adk.agents.llm_agent import Agent + +# Mock tool implementation +def get_current_time(city: str) -> dict: + """Returns the current time in a specified city.""" + if city.lower() == "new york": + return {"status": "success", "time": "10:30 AM EST"} + return {"status": "error", "message": f"Time for {city} not available."} + +root_agent = Agent( + model='gemini-2.5-flash', + name='root_agent', + description="Tells the current time in a specified city.", + instruction="You are a helpful assistant that tells the current time in cities. Use the 'get_current_time' tool for this purpose.", + tools=[get_current_time], +) +``` + +### Set your API key + +This project uses the Gemini API, which requires an API key. If you +don't already have Gemini API key, create a key in Google AI Studio on the +[API Keys](https://aistudio.google.com/app/apikey) page. + +In a terminal window, write your API key into an `.env` file as an environment variable: + +=== "Windows" + + ```console title="Update: my_agent/.env" + echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env + ``` + +=== "MacOS / Linux" + + ```bash title="Update: my_agent/.env" + echo 'export GOOGLE_API_KEY="YOUR_API_KEY"' > .env + ``` + +## Run your agent + +You can run your ADK agent with an interactive command-line interface using the +`adk run` command or the ADK web user interface provided by the ADK using the +`adk web` command. Both these options allow you to test and interact with your +agent. + +### Run with command-line interface + +Run your agent using the `adk run` command-line tool. + +```console +adk run my_agent +``` + +![adk-run.png](/adk-docs/assets/adk-run.png) + +### Run with web interface + +The ADK framework provides web interface you can use to test and interact with +your agent. You can start the web interface using the following command: + +```console +adk web my_agent +``` + +This command starts a web server with a chat interface for your agent. You can +access the web interface at (http://localhost:8080). Select the agent at the +upper right corner and type a request. + +![adk-web-dev-ui-chat.png](/adk-docs/assets/adk-web-dev-ui-chat.png) + +## Next: Build your agent + +Now that you have ADK installed and your first agent running, try building +your own agent with our build guides: + +* [Build your agent](/adk-docs/tutorials/) diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md index 672322ce7..0d14b64c5 100644 --- a/docs/get-started/quickstart.md +++ b/docs/get-started/quickstart.md @@ -1,4 +1,4 @@ -# Quickstart +# Build a multi-tool agent This quickstart guides you through installing the Agent Development Kit (ADK), setting up a basic agent with multiple tools, and running it locally either in the terminal or in the interactive, browser-based dev UI. diff --git a/docs/get-started/streaming/index.md b/docs/get-started/streaming/index.md index 02b0dd0d1..9700bb8b8 100644 --- a/docs/get-started/streaming/index.md +++ b/docs/get-started/streaming/index.md @@ -1,4 +1,4 @@ -# Streaming Quickstarts +# Build a streaming agent The Agent Development Kit (ADK) enables real-time, interactive experiences with your AI agents through streaming. This allows for features like live voice conversations, real-time tool use, and continuous updates from your agent. @@ -6,7 +6,7 @@ This page provides quickstart examples to get you up and running with streaming
-- :fontawesome-brands-python:{ .lg .middle } **Python ADK: Streaming Quickstart** +- :fontawesome-brands-python:{ .lg .middle } **Python ADK: Streaming agent** --- This example demonstrates how to set up a basic streaming interaction with an agent using Python ADK. It typically involves using the `Runner.run_live()` method and handling asynchronous events. @@ -16,7 +16,7 @@ This page provides quickstart examples to get you up and running with streaming -- :fontawesome-brands-java:{ .lg .middle } **Java ADK: Streaming Quickstart** +- :fontawesome-brands-java:{ .lg .middle } **Java ADK: Streaming agent** --- This example demonstrates how to set up a basic streaming interaction with an agent using Java ADK. It involves using the `Runner.runLive()` method, a `LiveRequestQueue`, and handling the `Flowable` stream. diff --git a/docs/get-started/streaming/quickstart-streaming-java.md b/docs/get-started/streaming/quickstart-streaming-java.md index 68de21024..94abf268a 100644 --- a/docs/get-started/streaming/quickstart-streaming-java.md +++ b/docs/get-started/streaming/quickstart-streaming-java.md @@ -1,4 +1,4 @@ -# Quickstart (Streaming / Java) {#adk-streaming-quickstart-java} +# Build a streaming agent with Java This quickstart guide will walk you through the process of creating a basic agent and leveraging ADK Streaming with Java to facilitate low-latency, bidirectional voice interactions. diff --git a/docs/get-started/streaming/quickstart-streaming.md b/docs/get-started/streaming/quickstart-streaming.md index 31b6a08f6..86f7e9dd1 100644 --- a/docs/get-started/streaming/quickstart-streaming.md +++ b/docs/get-started/streaming/quickstart-streaming.md @@ -1,4 +1,4 @@ -# Quickstart (Streaming / Python) {#adk-streaming-quickstart} +# Build a streaming agent with Python With this quickstart, you'll learn to create a simple agent and use ADK Streaming to enable voice and video communication with it that is low-latency and bidirectional. We will install ADK, set up a basic "Google Search" agent, try running the agent with Streaming with `adk web` tool, and then explain how to build a simple asynchronous web app by yourself using ADK Streaming and [FastAPI](https://fastapi.tiangolo.com/). diff --git a/docs/index.md b/docs/index.md index 8b6e8d4b8..50988ad7e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,10 +3,6 @@ hide: - toc --- -!!! tip "What's new" - Build agents without code. Check out the - [Agent Config](/adk-docs/agents/config/) feature. -
Agent Development Kit Logo @@ -14,8 +10,6 @@ hide:
-## What is Agent Development Kit? - Agent Development Kit (ADK) is a flexible and modular framework for **developing and deploying AI agents**. While optimized for Gemini and the Google ecosystem, ADK is **model-agnostic**, **deployment-agnostic**, and is built for @@ -51,13 +45,10 @@ from simple tasks to complex workflows. ```
-

- Quickstart - Tutorials - Sample Agents - API Reference - Contribute ❤️ + Start with Python + Start with Java + Technical overview

--- diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 169432e8f..e6ae34b63 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -1,4 +1,4 @@ -# ADK Tutorials! +# Build your agent with ADK Get started with the Agent Development Kit (ADK) through our collection of practical guides. These tutorials are designed in a simple, progressive, @@ -13,15 +13,37 @@ applications with ADK. Explore our collection below and happy building:
-- :material-console-line: **Agent Team** +- :material-console-line: **Multi-tool agent** --- - Learn to build an intelligent multi-agent weather bot and master key ADK - features: defining Tools, using multiple LLMs (Gemini, GPT, Claude) with - LiteLLM, orchestrating agent delegation, adding memory with session state, - and ensuring safety via callbacks. + Create a workflow that uses multiple tools. - [:octicons-arrow-right-24: Start learning here](agent-team.md) + [:octicons-arrow-right-24: Build a multi-tool agent](/adk-docs/get-started/index.md) + +- :material-console-line: **Agent team** + + --- + + Build an multi-agent workflow including agent delegation, + session management, and safety callbacks. + + [:octicons-arrow-right-24: Build an agent team](/adk-docs/tutorials/agent-team.md) + +- :material-console-line: **Streaming agent** + + --- + + Create an agent for handling streamed content. + + [:octicons-arrow-right-24: Build a streaming agent](/adk-docs/get-started/streaming/) + +- :material-rocket-launch-outline: **Discover sample agents** + + --- + + Discover sample agents for retail, travel, customer service, and more! + + [:octicons-arrow-right-24: Discover adk-samples](https://github.com/google/adk-samples){:target="_blank"}
diff --git a/mkdocs.yml b/mkdocs.yml index 059ab98d9..b66528595 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -114,20 +114,22 @@ plugins: # Navigation nav: - Home: index.md - - Get Started: + - Get started: - get-started/index.md - - Installation: get-started/installation.md - - Quickstart: get-started/quickstart.md - - Quickstart (Streaming): + - Python: get-started/python.md + - Java: get-started/java.md + - Build your agent: + - tutorials/index.md + - Multi-tool agent: get-started/quickstart.md + - Agent team: tutorials/agent-team.md + - Streaming agent: - get-started/streaming/index.md - Python: get-started/streaming/quickstart-streaming.md - Java: get-started/streaming/quickstart-streaming-java.md - Testing: get-started/testing.md - - Sample agents: https://github.com/google/adk-samples - - About ADK: get-started/about.md - - Tutorials: - - tutorials/index.md - - Agent Team: tutorials/agent-team.md + - Code samples: https://github.com/google/adk-samples + - Advanced setup: get-started/installation.md + - Technical overview: get-started/about.md - Agents: - agents/index.md - LLM agents: agents/llm-agents.md @@ -191,7 +193,7 @@ nav: - plugins/index.md - Bidi-streaming (live): - streaming/index.md - - Quickstart (Bidi-streaming/live): get-started/streaming/index.md + #- Quickstart (Bidi-streaming/live): get-started/streaming/index.md - Custom Audio Bidi-streaming app sample (SSE): streaming/custom-streaming.md - Custom Audio Bidi-streaming app sample (WebSockets): streaming/custom-streaming-ws.md - Bidi-streaming development guide series: streaming/dev-guide/part1.md