From 7d1144283811dee6f6b86617b41cb73c5bc32a7f Mon Sep 17 00:00:00 2001 From: Kamil Tomaszek Date: Thu, 8 Oct 2026 07:39:05 -0700 Subject: [PATCH] refactor: move the samples from contrib/samples to a top-level examples folder - The samples' parent POM is now `google-adk-examples`; `google-adk-samples` is no longer published. PiperOrigin-RevId: 995826284 --- a2a/README.md | 62 +++--- contrib/README.md | 4 +- contrib/samples/a2a_basic/README.md | 49 ----- contrib/samples/pom.xml | 25 --- examples/README.md | 19 ++ .../a2a_basic/A2AAgent.java | 0 .../a2a_basic/A2AAgentRun.java | 0 examples/a2a_basic/README.md | 49 +++++ .../samples => examples}/a2a_basic/pom.xml | 2 +- .../samples => examples}/a2a_server/README.md | 2 +- .../samples => examples}/a2a_server/pom.xml | 2 +- .../samples/a2aagent/AgentCardProducer.java | 0 .../a2aagent/AgentExecutorProducer.java | 0 .../adk/samples/a2aagent/StartupConfig.java | 0 .../adk/samples/a2aagent/agent/Agent.java | 0 .../src/main/resources/agent/agent.json | 0 .../src/main/resources/application.properties | 0 .../configagent/README.md | 184 +++++++++++------- .../core_basic_config/root_agent.yaml | 0 .../core_callback_config/root_agent.yaml | 0 .../root_agent.yaml | 0 .../code_tutor_agent.yaml | 0 .../math_tutor_agent.yaml | 0 .../multi_agent_basic_config/root_agent.yaml | 0 .../multi_agent_llm_config/prime_agent.yaml | 0 .../multi_agent_llm_config/roll_agent.yaml | 0 .../multi_agent_llm_config/root_agent.yaml | 0 .../samples => examples}/configagent/pom.xml | 2 +- .../main/java/com/example/CoreCallbacks.java | 0 .../java/com/example/CustomDemoRegistry.java | 0 .../main/java/com/example/CustomDieTool.java | 0 .../src/main/java/com/example/LifeAgent.java | 0 .../sub_agents_config/root_agent.yaml | 0 .../sub_agents_config/work_agent.yaml | 0 .../tool_builtin_config/root_agent.yaml | 0 .../tool_functions_config/root_agent.yaml | 0 .../root_agent.yaml | 0 .../helloworld/HelloWorldAgent.java | 0 .../helloworld/HelloWorldRun.java | 0 .../samples => examples}/helloworld/README.md | 12 +- .../samples => examples}/helloworld/pom.xml | 2 +- .../mcpfilesystem/McpFilesystemAgent.java | 0 .../mcpfilesystem/McpFilesystemRun.java | 0 .../mcpfilesystem/README.md | 52 ++--- .../mcpfilesystem/pom.xml | 6 +- examples/pom.xml | 40 ++++ pom.xml | 2 +- 47 files changed, 296 insertions(+), 218 deletions(-) delete mode 100644 contrib/samples/a2a_basic/README.md delete mode 100644 contrib/samples/pom.xml create mode 100644 examples/README.md rename {contrib/samples => examples}/a2a_basic/A2AAgent.java (100%) rename {contrib/samples => examples}/a2a_basic/A2AAgentRun.java (100%) create mode 100644 examples/a2a_basic/README.md rename {contrib/samples => examples}/a2a_basic/pom.xml (98%) rename {contrib/samples => examples}/a2a_server/README.md (98%) rename {contrib/samples => examples}/a2a_server/pom.xml (98%) rename {contrib/samples => examples}/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentCardProducer.java (100%) rename {contrib/samples => examples}/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentExecutorProducer.java (100%) rename {contrib/samples => examples}/a2a_server/src/main/java/com/google/adk/samples/a2aagent/StartupConfig.java (100%) rename {contrib/samples => examples}/a2a_server/src/main/java/com/google/adk/samples/a2aagent/agent/Agent.java (100%) rename {contrib/samples => examples}/a2a_server/src/main/resources/agent/agent.json (100%) rename {contrib/samples => examples}/a2a_server/src/main/resources/application.properties (100%) rename {contrib/samples => examples}/configagent/README.md (51%) rename {contrib/samples => examples}/configagent/core_basic_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/core_callback_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/core_generate_content_config_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/multi_agent_basic_config/code_tutor_agent.yaml (100%) rename {contrib/samples => examples}/configagent/multi_agent_basic_config/math_tutor_agent.yaml (100%) rename {contrib/samples => examples}/configagent/multi_agent_basic_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/multi_agent_llm_config/prime_agent.yaml (100%) rename {contrib/samples => examples}/configagent/multi_agent_llm_config/roll_agent.yaml (100%) rename {contrib/samples => examples}/configagent/multi_agent_llm_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/pom.xml (97%) rename {contrib/samples => examples}/configagent/src/main/java/com/example/CoreCallbacks.java (100%) rename {contrib/samples => examples}/configagent/src/main/java/com/example/CustomDemoRegistry.java (100%) rename {contrib/samples => examples}/configagent/src/main/java/com/example/CustomDieTool.java (100%) rename {contrib/samples => examples}/configagent/src/main/java/com/example/LifeAgent.java (100%) rename {contrib/samples => examples}/configagent/sub_agents_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/sub_agents_config/work_agent.yaml (100%) rename {contrib/samples => examples}/configagent/tool_builtin_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/tool_functions_config/root_agent.yaml (100%) rename {contrib/samples => examples}/configagent/tool_mcp_stdio_file_system_config/root_agent.yaml (100%) rename {contrib/samples => examples}/helloworld/HelloWorldAgent.java (100%) rename {contrib/samples => examples}/helloworld/HelloWorldRun.java (100%) rename {contrib/samples => examples}/helloworld/README.md (79%) rename {contrib/samples => examples}/helloworld/pom.xml (98%) rename {contrib/samples => examples}/mcpfilesystem/McpFilesystemAgent.java (100%) rename {contrib/samples => examples}/mcpfilesystem/McpFilesystemRun.java (100%) rename {contrib/samples => examples}/mcpfilesystem/README.md (52%) rename {contrib/samples => examples}/mcpfilesystem/pom.xml (96%) create mode 100644 examples/pom.xml diff --git a/a2a/README.md b/a2a/README.md index 139fac1e3..1b8bbf14b 100644 --- a/a2a/README.md +++ b/a2a/README.md @@ -89,58 +89,43 @@ tools. The `a2a/webservice` module packages the Spring Boot transport that exposes the REST endpoint: -- `A2ARemoteApplication` – Spring Boot entrypoint that boots the Tomcat server - and wires in the remote configuration. -- `A2ARemoteConfiguration` – Spring `@Configuration` that imports the transport - stack and the shared `A2ASendMessageExecutor`. Provide a `BaseAgent` bean to - handle requests locally (as the `a2a_remote` sample does). -- `A2ARemoteController` – JSON-RPC adapter mounted at `/a2a/remote/v1`. -- `A2ARemoteService` – delegates incoming requests to the executor and handles - JSON-RPC error responses. +- `A2ARemoteApplication` – Spring Boot entrypoint that boots the Tomcat server + and wires in the remote configuration. +- `A2ARemoteConfiguration` – Spring `@Configuration` that imports the + transport stack and the shared `A2ASendMessageExecutor`. Provide a + `BaseAgent` bean to handle requests locally. +- `A2ARemoteController` – JSON-RPC adapter mounted at `/a2a/remote/v1`. +- `A2ARemoteService` – delegates incoming requests to the executor and handles + JSON-RPC error responses. All application wiring lives in this module; the core A2A logic remains in the transport-agnostic `a2a/src/...` tree described above. ### Samples -- `contrib/samples/a2a_basic` – minimal HTTP client demo that hits a remote - A2A endpoint and logs the JSON-RPC exchange. Useful for verifying the - transport without standing up the full Spring service. -- `contrib/samples/a2a_remote` – standalone Spring service mirroring the - Stubby demo. It depends on the shared `a2a/webservice` module so the sample - only provides the prime-agent wiring while reusing the production controller - and service stack. +- `examples/a2a_basic` – minimal HTTP client demo that hits a remote A2A + endpoint and logs the JSON-RPC exchange. Useful for verifying the transport + against a running A2A server, such as `examples/a2a_server`. +- `examples/a2a_server` – Quarkus service that exposes a prime-checking ADK + agent over A2A on port 9090; its README shows how to run and call it. ### Quick Start All commands below assume you are in `google_adk`. -1. **Start the Spring webservice sample** (run in its own terminal) +1. **Start the A2A server sample (`a2a_server`)** (run in its own terminal) ```bash - lsof -ti :8081 | xargs -r kill - ./mvnw -f contrib/samples/a2a_remote/pom.xml spring-boot:run \ - -Dspring-boot.run.arguments=--server.port=8081 - ``` - - Background option: - - ```bash - nohup env GOOGLE_GENAI_USE_VERTEXAI=FALSE \ - GOOGLE_API_KEY=your_api_key \ - ./mvnw -f contrib/samples/a2a_remote/pom.xml spring-boot:run \ - -Dspring-boot.run.arguments=--server.port=8081 \ - > /tmp/a2a_webservice.log 2>&1 & echo $! + GOOGLE_API_KEY=your_api_key \ + ./mvnw -f examples/a2a_server/pom.xml quarkus:dev ``` - The log can be found at /tmp/a2a_webservice.log. - -2. **Run the basic client sample (`a2a_basic`)** (from another terminal) +2. **Run the basic client sample (`a2a_basic`)** (from another terminal) ```bash GOOGLE_GENAI_USE_VERTEXAI=FALSE \ GOOGLE_API_KEY=your_api_key \ - ./mvnw -f contrib/samples/a2a_basic/pom.xml exec:java \ - -Dexec.args="http://localhost:8081/a2a/remote" + ./mvnw -f examples/a2a_basic/pom.xml exec:java \ + -Dexec.args="http://localhost:9090" ``` The client logs the outbound JSON-RPC payload and shows the remote agent’s @@ -155,15 +140,14 @@ All commands below assume you are in `google_adk`. ```bash nohup env GOOGLE_GENAI_USE_VERTEXAI=FALSE \ GOOGLE_API_KEY=your_api_key \ - ./mvnw -f contrib/samples/a2a_basic/pom.xml exec:java \ - -Dexec.args="http://localhost:8081/a2a/remote" \ + ./mvnw -f examples/a2a_basic/pom.xml exec:java \ + -Dexec.args="http://localhost:9090" \ > /tmp/a2a_basic.log 2>&1 & echo $! ``` Tail `/tmp/a2a_basic.log` to observe subsequent turns. -To build the runtime, Spring webservice, and both samples together, activate the -opt-in Maven profile: +To build the A2A runtime: ```bash ./mvnw -pl a2a -am clean package @@ -174,7 +158,7 @@ opt-in Maven profile: With the server running locally you can exercise the endpoint with `curl`: ```bash -curl -X POST http://localhost:8081/a2a/remote/v1/message:send \ +curl -X POST http://localhost:9090 \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", diff --git a/contrib/README.md b/contrib/README.md index 2368ef057..08cf44edd 100644 --- a/contrib/README.md +++ b/contrib/README.md @@ -5,7 +5,9 @@ Please take a look at [ADK Contribution Guidelines](https://google.github.io/adk ## Samples -The samples folder hosts minimal examples to test different features. These samples are intentionally simplistic and focused on testing specific scenarios. +Minimal examples that test different features live in the top-level +[`examples`](../examples) folder. They are intentionally simplistic and focused +on testing specific scenarios. **Note:** This is different from the [google/adk-samples](https://github.com/google/adk-samples) repository, which hosts more complex end-to-end samples for customers to use or modify directly. diff --git a/contrib/samples/a2a_basic/README.md b/contrib/samples/a2a_basic/README.md deleted file mode 100644 index 4d2c793ae..000000000 --- a/contrib/samples/a2a_basic/README.md +++ /dev/null @@ -1,49 +0,0 @@ -# A2A Basic Sample - -This sample shows how to invoke an A2A-compliant HTTP endpoint from the Google -ADK runtime using the reusable `google-adk-a2a` module. It wires a -`RemoteA2AAgent` to the production `JdkA2AHttpClient`, so you can exercise a -running service (for example the Spring Boot webservice in -`a2a/webservice`). - -## Prerequisites - -1. Start the Spring service (or point to any other A2A-compliant endpoint): - - ```bash - cd /google_adk - ./mvnw -f a2a/webservice/pom.xml spring-boot:run \ - -Dspring-boot.run.arguments=--server.port=8081 - ``` - -## Build and run - -```bash -cd google_adk -./mvnw -f contrib/samples/a2a_basic/pom.xml exec:java \ - -Dexec.args="http://localhost:8081/a2a/remote" -``` - -You should see the client log each turn, including the remote agent response -(e.g. `4 is not a prime number.`). - -To run the client in the background and capture logs: - -```bash -nohup env GOOGLE_GENAI_USE_VERTEXAI=FALSE \ - GOOGLE_API_KEY=your_api_key \ - ./mvnw -f contrib/samples/a2a_basic/pom.xml exec:java \ - -Dexec.args="http://localhost:8081/a2a/remote" \ - > /tmp/a2a_basic.log 2>&1 & echo $! -``` - -Tail `/tmp/a2a_basic.log` to inspect the conversation. - -## Key files - -- `A2AAgent.java` – builds a root agent with a local dice-rolling tool and a - remote prime-checking sub-agent. -- `A2AAgentRun.java` – minimal driver that executes a single - `SendMessage` turn to demonstrate the remote call. -- `pom.xml` – standalone Maven configuration for building and running the - sample. diff --git a/contrib/samples/pom.xml b/contrib/samples/pom.xml deleted file mode 100644 index 931ddae19..000000000 --- a/contrib/samples/pom.xml +++ /dev/null @@ -1,25 +0,0 @@ - - - 4.0.0 - - - com.google.adk - google-adk-parent - 1.11.1-SNAPSHOT - ../.. - - - google-adk-samples - pom - - Google ADK Samples - Aggregator for sample applications. - - - a2a_basic - a2a_server - configagent - helloworld - mcpfilesystem - - diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..7ab11f6b1 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,19 @@ +# ADK Java examples + +This directory contains minimal examples that each show one or a few ADK +features. Each example is its own Maven module, and its README shows how to run +it. + +These examples differ from the +[google/adk-samples](https://github.com/google/adk-samples) repository, which +contains more complete end-to-end samples for customers to use or modify. + +- [`a2a_basic`](a2a_basic/README.md): an ADK agent that calls a remote agent + over A2A. +- [`a2a_server`](a2a_server/README.md): an ADK agent served over A2A with + Quarkus. +- [`configagent`](configagent/README.md): agents defined in YAML config files. +- [`helloworld`](helloworld/README.md): a minimal agent with dice-rolling and + prime-checking tools. +- [`mcpfilesystem`](mcpfilesystem/README.md): an agent that uses the MCP + filesystem server as a toolset. diff --git a/contrib/samples/a2a_basic/A2AAgent.java b/examples/a2a_basic/A2AAgent.java similarity index 100% rename from contrib/samples/a2a_basic/A2AAgent.java rename to examples/a2a_basic/A2AAgent.java diff --git a/contrib/samples/a2a_basic/A2AAgentRun.java b/examples/a2a_basic/A2AAgentRun.java similarity index 100% rename from contrib/samples/a2a_basic/A2AAgentRun.java rename to examples/a2a_basic/A2AAgentRun.java diff --git a/examples/a2a_basic/README.md b/examples/a2a_basic/README.md new file mode 100644 index 000000000..8ce9bbdcf --- /dev/null +++ b/examples/a2a_basic/README.md @@ -0,0 +1,49 @@ +# A2A Basic Sample + +This sample shows how to invoke an A2A-compliant HTTP endpoint from the Google +ADK runtime using the reusable `google-adk-a2a` module. It wires a +`RemoteA2AAgent` to the production `JdkA2AHttpClient`, so you can exercise a +running service (for example the `a2a_server` sample). + +## Prerequisites + +1. Start the `a2a_server` sample (or point to any other A2A-compliant + endpoint): + + ```bash + cd google_adk + GOOGLE_API_KEY=your_api_key \ + ./mvnw -f examples/a2a_server/pom.xml quarkus:dev + ``` + +## Build and run + +```bash +cd google_adk +./mvnw -f examples/a2a_basic/pom.xml exec:java \ + -Dexec.args="http://localhost:9090" +``` + +You should see the client log each turn, including the remote agent response +(e.g. `4 is not a prime number.`). + +To run the client in the background and capture logs: + +```bash +nohup env GOOGLE_GENAI_USE_VERTEXAI=FALSE \ + GOOGLE_API_KEY=your_api_key \ + ./mvnw -f examples/a2a_basic/pom.xml exec:java \ + -Dexec.args="http://localhost:9090" \ + > /tmp/a2a_basic.log 2>&1 & echo $! +``` + +Tail `/tmp/a2a_basic.log` to inspect the conversation. + +## Key files + +- `A2AAgent.java` – builds a root agent with a local dice-rolling tool and a + remote prime-checking sub-agent. +- `A2AAgentRun.java` – minimal driver that executes a single `SendMessage` + turn to demonstrate the remote call. +- `pom.xml` – standalone Maven configuration for building and running the + sample. diff --git a/contrib/samples/a2a_basic/pom.xml b/examples/a2a_basic/pom.xml similarity index 98% rename from contrib/samples/a2a_basic/pom.xml rename to examples/a2a_basic/pom.xml index 5b23cef38..9a40096b5 100644 --- a/contrib/samples/a2a_basic/pom.xml +++ b/examples/a2a_basic/pom.xml @@ -4,7 +4,7 @@ com.google.adk - google-adk-samples + google-adk-examples 1.11.1-SNAPSHOT .. diff --git a/contrib/samples/a2a_server/README.md b/examples/a2a_server/README.md similarity index 98% rename from contrib/samples/a2a_server/README.md rename to examples/a2a_server/README.md index 5351e32c0..0596366e1 100644 --- a/contrib/samples/a2a_server/README.md +++ b/examples/a2a_server/README.md @@ -39,7 +39,7 @@ GOOGLE_API_KEY before running the service): ```bash export GOOGLE_API_KEY= -cd contrib/samples/a2a_server +cd examples/a2a_server mvn quarkus:dev ``` diff --git a/contrib/samples/a2a_server/pom.xml b/examples/a2a_server/pom.xml similarity index 98% rename from contrib/samples/a2a_server/pom.xml rename to examples/a2a_server/pom.xml index 08d68d5a0..eeafaf17b 100644 --- a/contrib/samples/a2a_server/pom.xml +++ b/examples/a2a_server/pom.xml @@ -4,7 +4,7 @@ com.google.adk - google-adk-samples + google-adk-examples 1.11.1-SNAPSHOT .. diff --git a/contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentCardProducer.java b/examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentCardProducer.java similarity index 100% rename from contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentCardProducer.java rename to examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentCardProducer.java diff --git a/contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentExecutorProducer.java b/examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentExecutorProducer.java similarity index 100% rename from contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentExecutorProducer.java rename to examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/AgentExecutorProducer.java diff --git a/contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/StartupConfig.java b/examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/StartupConfig.java similarity index 100% rename from contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/StartupConfig.java rename to examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/StartupConfig.java diff --git a/contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/agent/Agent.java b/examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/agent/Agent.java similarity index 100% rename from contrib/samples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/agent/Agent.java rename to examples/a2a_server/src/main/java/com/google/adk/samples/a2aagent/agent/Agent.java diff --git a/contrib/samples/a2a_server/src/main/resources/agent/agent.json b/examples/a2a_server/src/main/resources/agent/agent.json similarity index 100% rename from contrib/samples/a2a_server/src/main/resources/agent/agent.json rename to examples/a2a_server/src/main/resources/agent/agent.json diff --git a/contrib/samples/a2a_server/src/main/resources/application.properties b/examples/a2a_server/src/main/resources/application.properties similarity index 100% rename from contrib/samples/a2a_server/src/main/resources/application.properties rename to examples/a2a_server/src/main/resources/application.properties diff --git a/contrib/samples/configagent/README.md b/examples/configagent/README.md similarity index 51% rename from contrib/samples/configagent/README.md rename to examples/configagent/README.md index a63a4a113..6dd07f078 100644 --- a/contrib/samples/configagent/README.md +++ b/examples/configagent/README.md @@ -1,16 +1,23 @@ # Config-based Agent Samples -This directory contains several samples demonstrating ADK agent configuration using YAML files: - -1. **Core Basic Config** - The simplest possible agent configuration -2. **Core Callback Config** - An agent with comprehensive callback hooks for lifecycle events -3. **Core Generate Content Config** - An agent demonstrating generate_content_config settings -4. **Tool Builtin Config** - An agent with built-in Google search tool -5. **Tool Functions Config** - An agent with custom Java-based function tools -6. **Multi Agent Basic Config** - Multiple specialized agents (coding tutor, math tutor) -7. **Multi Agent LLM Config** - Multi-agent system with dice rolling and prime checking capabilities -8. **Tool MCP Stdio File System Config** - An agent with MCP filesystem tools via stdio transport -9. **Sub Agents Config** - Demonstrates programmatic sub-agent resolution using the `code` field +This directory contains several samples demonstrating ADK agent configuration +using YAML files: + +1. **Core Basic Config** - The simplest possible agent configuration +2. **Core Callback Config** - An agent with comprehensive callback hooks for + lifecycle events +3. **Core Generate Content Config** - An agent demonstrating + generate_content_config settings +4. **Tool Builtin Config** - An agent with built-in Google search tool +5. **Tool Functions Config** - An agent with custom Java-based function tools +6. **Multi Agent Basic Config** - Multiple specialized agents (coding tutor, + math tutor) +7. **Multi Agent LLM Config** - Multi-agent system with dice rolling and prime + checking capabilities +8. **Tool MCP Stdio File System Config** - An agent with MCP filesystem tools + via stdio transport +9. **Sub Agents Config** - Demonstrates programmatic sub-agent resolution using + the `code` field ## Project Structure @@ -50,18 +57,22 @@ This directory contains several samples demonstrating ADK agent configuration us ## How to Use ### 1. Navigate to this sample directory + ```bash -cd contrib/samples/configagent +cd examples/configagent ``` ### 2. Run the ADK web server + Run all agents simultaneously: + ```bash mvn clean compile google-adk:web -Dagents=. \ -Dregistry=com.example.CustomDemoRegistry ``` Or run individual agents: + ```bash # Basic agent only mvn google-adk:web -Dagents=core_basic_config @@ -73,7 +84,9 @@ mvn clean compile google-adk:web \ ``` ### 3. Access the Web UI + Open your browser and navigate to: + ``` http://localhost:8000 ``` @@ -85,29 +98,37 @@ You will see the configured agent(s) available in the UI. Basic Q&A agent with essential fields: name, model, description, instruction. **Sample queries:** -- "Hello, can you help me?" -- "Explain what machine learning is" -## Sample 2: Core Callback Config (`core_callback_config/`) +- "Hello, can you help me?" +- "Explain what machine learning is" -Agent demonstrating comprehensive callback hooks for monitoring and debugging agent lifecycle events. This sample showcases how callbacks can be used to track agent execution, model interactions, and tool usage. +## Sample 2: Core Callback Config (`core_callback_config/`) +Agent demonstrating comprehensive callback hooks for monitoring and debugging +agent lifecycle events. This sample showcases how callbacks can be used to track +agent execution, model interactions, and tool usage. **Sample queries:** -- "Roll a 6-sided die" - Triggers tool callbacks -- "Roll a 20-sided die and check if it's prime" - Demonstrates multiple callback types -- "Check if 7, 11, and 13 are prime numbers" - Shows batch processing with callbacks + +- "Roll a 6-sided die" - Triggers tool callbacks +- "Roll a 20-sided die and check if it's prime" - Demonstrates multiple + callback types +- "Check if 7, 11, and 13 are prime numbers" - Shows batch processing with + callbacks **Callback Types:** -- **Agent callbacks**: Execute before/after the agent processes a request -- **Model callbacks**: Execute before/after LLM invocation -- **Tool callbacks**: Execute before/after tool execution + +- **Agent callbacks**: Execute before/after the agent processes a request +- **Model callbacks**: Execute before/after LLM invocation +- **Tool callbacks**: Execute before/after tool execution ## Sample 3: Core Generate Content Config (`core_generate_content_config_config/`) -Search agent demonstrating the use of `generate_content_config` to control LLM generation parameters. +Search agent demonstrating the use of `generate_content_config` to control LLM +generation parameters. **Key Configuration:** + ```yaml generate_content_config: temperature: 0.1 # Lower temperature for more focused responses @@ -115,94 +136,123 @@ generate_content_config: ``` **Sample queries that demonstrate the configuration:** -- "Generate a creative story about a robot" - Run this multiple times; with temperature 0.1, you'll get very similar stories each time (low creativity/high consistency) -- "List 3 uses for a paperclip" - Run multiple times; low temperature means you'll likely get the same common uses each time (writing, holding papers, reset button) -- "Search for machine learning frameworks and provide a comprehensive comparison" - Tests the max_output_tokens limit of 2000; response will be truncated if it exceeds this limit + +- "Generate a creative story about a robot" - Run this multiple times; with + temperature 0.1, you'll get very similar stories each time (low + creativity/high consistency) +- "List 3 uses for a paperclip" - Run multiple times; low temperature means + you'll likely get the same common uses each time (writing, holding papers, + reset button) +- "Search for machine learning frameworks and provide a comprehensive + comparison" - Tests the max_output_tokens limit of 2000; response will be + truncated if it exceeds this limit ## Sample 4: Tool Builtin Config (`tool_builtin_config/`) Search agent with built-in Google search tool. **Sample queries:** -- "Search for the latest news about artificial intelligence" -- "What are the top Python frameworks in 2024?" + +- "Search for the latest news about artificial intelligence" +- "What are the top Python frameworks in 2024?" ## Sample 5: Tool Functions Config (`tool_functions_config/`) -Agent with custom Java-based function tools for dice rolling and prime number checking. +Agent with custom Java-based function tools for dice rolling and prime number +checking. **Custom Tools:** -- `roll_die(sides)` - Rolls a die with specified number of sides -- `check_prime(nums)` - Checks if a list of numbers are prime + +- `roll_die(sides)` - Rolls a die with specified number of sides +- `check_prime(nums)` - Checks if a list of numbers are prime **Sample queries:** -- "Roll a 6-sided die" -- "Roll a 20-sided die and check if the result is prime" + +- "Roll a 6-sided die" +- "Roll a 20-sided die and check if the result is prime" ## Sample 6: Multi Agent Basic Config (`multi_agent_basic_config/`) -Learning assistant with specialized sub-agents for coding and math tutoring. The root agent coordinates between specialized tutors. +Learning assistant with specialized sub-agents for coding and math tutoring. The +root agent coordinates between specialized tutors. **Sub-agents:** -- `code_tutor_agent` - Programming concepts and code debugging -- `math_tutor_agent` - Mathematical concepts and problem solving + +- `code_tutor_agent` - Programming concepts and code debugging +- `math_tutor_agent` - Mathematical concepts and problem solving **Sample queries:** -- "How do I write a for loop in Python?" -- "Explain what recursion is with an example" + +- "How do I write a for loop in Python?" +- "Explain what recursion is with an example" ## Sample 7: Multi Agent LLM Config (`multi_agent_llm_config/`) -Multi-agent system demonstrating delegation between specialized agents for dice rolling and prime number checking. Includes few-shot examples and safety settings configuration. +Multi-agent system demonstrating delegation between specialized agents for dice +rolling and prime number checking. Includes few-shot examples and safety +settings configuration. **Sub-agents:** -- `roll_agent` - Handles dice rolling with different sizes -- `prime_agent` - Checks whether numbers are prime + +- `roll_agent` - Handles dice rolling with different sizes +- `prime_agent` - Checks whether numbers are prime **Features:** -- Demonstrates multi-agent coordination and delegation -- Uses custom Java tools (roll_die, check_prime) -- Includes few-shot examples via ExampleTool -- Shows safety settings configuration -- Root agent delegates tasks to specialized sub-agents + +- Demonstrates multi-agent coordination and delegation +- Uses custom Java tools (roll_die, check_prime) +- Includes few-shot examples via ExampleTool +- Shows safety settings configuration +- Root agent delegates tasks to specialized sub-agents **Sample queries:** -- "Roll a 6-sided die" -- "Roll a 20-sided die and check if the result is prime" + +- "Roll a 6-sided die" +- "Roll a 20-sided die and check if the result is prime" ## Sample 8: Tool MCP Stdio File System Config (`tool_mcp_stdio_file_system_config/`) -File system assistant using Model Context Protocol (MCP) stdio transport to manage files and directories. +File system assistant using Model Context Protocol (MCP) stdio transport to +manage files and directories. **Features:** -- Connects to file system via MCP stdio server -- Read, write, search, and manage files and directories -- Uses `@modelcontextprotocol/server-filesystem` npm package -- Works with `/tmp/mcp-demo` directory + +- Connects to file system via MCP stdio server +- Read, write, search, and manage files and directories +- Uses `@modelcontextprotocol/server-filesystem` npm package +- Works with `/tmp/mcp-demo` directory **Setup:** -1. Ensure you have Node.js installed -2. Create the demo directory: `mkdir -p /tmp/mcp-demo` -3. Run the agent: + +1. Ensure you have Node.js installed +2. Create the demo directory: `mkdir -p /tmp/mcp-demo` +3. Run the agent: + ```bash mvn google-adk:web -Dagents=tool_mcp_stdio_file_system_config -Dport=8001 ``` **Sample queries:** -- "List all files in the current directory" -- "Create a new file called 'notes.txt' in /tmp/mcp-demo with some random content" + +- "List all files in the current directory" +- "Create a new file called 'notes.txt' in /tmp/mcp-demo with some random + content" ## Sample 9: Sub Agents Config (`sub_agents_config/`) -Demonstrates programmatic sub-agent resolution using the `code` field, which provides Python ADK compatibility. This sample shows how to reference agents registered in the ComponentRegistry. +Demonstrates programmatic sub-agent resolution using the `code` field, which +provides Python ADK compatibility. This sample shows how to reference agents +registered in the ComponentRegistry. **Features:** -- Root agent that routes queries to different sub-agents -- Life agent loaded programmatically via `code` field -- Work agent loaded from YAML config file -- Uses CustomDemoRegistry to register the LifeAgent + +- Root agent that routes queries to different sub-agents +- Life agent loaded programmatically via `code` field +- Work agent loaded from YAML config file +- Uses CustomDemoRegistry to register the LifeAgent **Configuration Example:** + ```yaml sub_agents: - config_path: ./work_agent.yaml # Traditional YAML file reference @@ -210,6 +260,7 @@ sub_agents: ``` **Setup:** + ```bash mvn clean compile google-adk:web \ -Dagents=sub_agents_config \ @@ -217,6 +268,7 @@ mvn clean compile google-adk:web \ ``` **Sample queries:** -- "What is the meaning of life?" (routed to life agent) -- "How can I be more productive at work?" (routed to work agent) -- "Tell me about the weather" (handled by root agent) + +- "What is the meaning of life?" (routed to life agent) +- "How can I be more productive at work?" (routed to work agent) +- "Tell me about the weather" (handled by root agent) diff --git a/contrib/samples/configagent/core_basic_config/root_agent.yaml b/examples/configagent/core_basic_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/core_basic_config/root_agent.yaml rename to examples/configagent/core_basic_config/root_agent.yaml diff --git a/contrib/samples/configagent/core_callback_config/root_agent.yaml b/examples/configagent/core_callback_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/core_callback_config/root_agent.yaml rename to examples/configagent/core_callback_config/root_agent.yaml diff --git a/contrib/samples/configagent/core_generate_content_config_config/root_agent.yaml b/examples/configagent/core_generate_content_config_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/core_generate_content_config_config/root_agent.yaml rename to examples/configagent/core_generate_content_config_config/root_agent.yaml diff --git a/contrib/samples/configagent/multi_agent_basic_config/code_tutor_agent.yaml b/examples/configagent/multi_agent_basic_config/code_tutor_agent.yaml similarity index 100% rename from contrib/samples/configagent/multi_agent_basic_config/code_tutor_agent.yaml rename to examples/configagent/multi_agent_basic_config/code_tutor_agent.yaml diff --git a/contrib/samples/configagent/multi_agent_basic_config/math_tutor_agent.yaml b/examples/configagent/multi_agent_basic_config/math_tutor_agent.yaml similarity index 100% rename from contrib/samples/configagent/multi_agent_basic_config/math_tutor_agent.yaml rename to examples/configagent/multi_agent_basic_config/math_tutor_agent.yaml diff --git a/contrib/samples/configagent/multi_agent_basic_config/root_agent.yaml b/examples/configagent/multi_agent_basic_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/multi_agent_basic_config/root_agent.yaml rename to examples/configagent/multi_agent_basic_config/root_agent.yaml diff --git a/contrib/samples/configagent/multi_agent_llm_config/prime_agent.yaml b/examples/configagent/multi_agent_llm_config/prime_agent.yaml similarity index 100% rename from contrib/samples/configagent/multi_agent_llm_config/prime_agent.yaml rename to examples/configagent/multi_agent_llm_config/prime_agent.yaml diff --git a/contrib/samples/configagent/multi_agent_llm_config/roll_agent.yaml b/examples/configagent/multi_agent_llm_config/roll_agent.yaml similarity index 100% rename from contrib/samples/configagent/multi_agent_llm_config/roll_agent.yaml rename to examples/configagent/multi_agent_llm_config/roll_agent.yaml diff --git a/contrib/samples/configagent/multi_agent_llm_config/root_agent.yaml b/examples/configagent/multi_agent_llm_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/multi_agent_llm_config/root_agent.yaml rename to examples/configagent/multi_agent_llm_config/root_agent.yaml diff --git a/contrib/samples/configagent/pom.xml b/examples/configagent/pom.xml similarity index 97% rename from contrib/samples/configagent/pom.xml rename to examples/configagent/pom.xml index 26aa9c371..5f23e4dd8 100644 --- a/contrib/samples/configagent/pom.xml +++ b/examples/configagent/pom.xml @@ -4,7 +4,7 @@ com.google.adk - google-adk-samples + google-adk-examples 1.11.1-SNAPSHOT .. diff --git a/contrib/samples/configagent/src/main/java/com/example/CoreCallbacks.java b/examples/configagent/src/main/java/com/example/CoreCallbacks.java similarity index 100% rename from contrib/samples/configagent/src/main/java/com/example/CoreCallbacks.java rename to examples/configagent/src/main/java/com/example/CoreCallbacks.java diff --git a/contrib/samples/configagent/src/main/java/com/example/CustomDemoRegistry.java b/examples/configagent/src/main/java/com/example/CustomDemoRegistry.java similarity index 100% rename from contrib/samples/configagent/src/main/java/com/example/CustomDemoRegistry.java rename to examples/configagent/src/main/java/com/example/CustomDemoRegistry.java diff --git a/contrib/samples/configagent/src/main/java/com/example/CustomDieTool.java b/examples/configagent/src/main/java/com/example/CustomDieTool.java similarity index 100% rename from contrib/samples/configagent/src/main/java/com/example/CustomDieTool.java rename to examples/configagent/src/main/java/com/example/CustomDieTool.java diff --git a/contrib/samples/configagent/src/main/java/com/example/LifeAgent.java b/examples/configagent/src/main/java/com/example/LifeAgent.java similarity index 100% rename from contrib/samples/configagent/src/main/java/com/example/LifeAgent.java rename to examples/configagent/src/main/java/com/example/LifeAgent.java diff --git a/contrib/samples/configagent/sub_agents_config/root_agent.yaml b/examples/configagent/sub_agents_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/sub_agents_config/root_agent.yaml rename to examples/configagent/sub_agents_config/root_agent.yaml diff --git a/contrib/samples/configagent/sub_agents_config/work_agent.yaml b/examples/configagent/sub_agents_config/work_agent.yaml similarity index 100% rename from contrib/samples/configagent/sub_agents_config/work_agent.yaml rename to examples/configagent/sub_agents_config/work_agent.yaml diff --git a/contrib/samples/configagent/tool_builtin_config/root_agent.yaml b/examples/configagent/tool_builtin_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/tool_builtin_config/root_agent.yaml rename to examples/configagent/tool_builtin_config/root_agent.yaml diff --git a/contrib/samples/configagent/tool_functions_config/root_agent.yaml b/examples/configagent/tool_functions_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/tool_functions_config/root_agent.yaml rename to examples/configagent/tool_functions_config/root_agent.yaml diff --git a/contrib/samples/configagent/tool_mcp_stdio_file_system_config/root_agent.yaml b/examples/configagent/tool_mcp_stdio_file_system_config/root_agent.yaml similarity index 100% rename from contrib/samples/configagent/tool_mcp_stdio_file_system_config/root_agent.yaml rename to examples/configagent/tool_mcp_stdio_file_system_config/root_agent.yaml diff --git a/contrib/samples/helloworld/HelloWorldAgent.java b/examples/helloworld/HelloWorldAgent.java similarity index 100% rename from contrib/samples/helloworld/HelloWorldAgent.java rename to examples/helloworld/HelloWorldAgent.java diff --git a/contrib/samples/helloworld/HelloWorldRun.java b/examples/helloworld/HelloWorldRun.java similarity index 100% rename from contrib/samples/helloworld/HelloWorldRun.java rename to examples/helloworld/HelloWorldRun.java diff --git a/contrib/samples/helloworld/README.md b/examples/helloworld/README.md similarity index 79% rename from contrib/samples/helloworld/README.md rename to examples/helloworld/README.md index 77fbb3cae..7ab6c9fd5 100644 --- a/contrib/samples/helloworld/README.md +++ b/examples/helloworld/README.md @@ -19,8 +19,8 @@ config-based collection in `../configagent/README.md`. ## Prerequisites -- Java 17+ -- Maven 3.9+ +- Java 17+ +- Maven 3.9+ ## Build and Run @@ -40,7 +40,7 @@ mvn exec:java -Dexec.args="--run-extended" ## Next Steps -* Review `HelloWorldAgent.java` to see how function tools are registered. -* Compare with the configuration-based samples in `../configagent/README.md` for - more complex agent setups (callbacks, multi-agent coordination, and custom - registries). +* Review `HelloWorldAgent.java` to see how function tools are registered. +* Compare with the configuration-based samples in `../configagent/README.md` + for more complex agent setups (callbacks, multi-agent coordination, and + custom registries). diff --git a/contrib/samples/helloworld/pom.xml b/examples/helloworld/pom.xml similarity index 98% rename from contrib/samples/helloworld/pom.xml rename to examples/helloworld/pom.xml index d54d5dced..707fba12d 100644 --- a/contrib/samples/helloworld/pom.xml +++ b/examples/helloworld/pom.xml @@ -19,7 +19,7 @@ com.google.adk - google-adk-samples + google-adk-examples 1.11.1-SNAPSHOT .. diff --git a/contrib/samples/mcpfilesystem/McpFilesystemAgent.java b/examples/mcpfilesystem/McpFilesystemAgent.java similarity index 100% rename from contrib/samples/mcpfilesystem/McpFilesystemAgent.java rename to examples/mcpfilesystem/McpFilesystemAgent.java diff --git a/contrib/samples/mcpfilesystem/McpFilesystemRun.java b/examples/mcpfilesystem/McpFilesystemRun.java similarity index 100% rename from contrib/samples/mcpfilesystem/McpFilesystemRun.java rename to examples/mcpfilesystem/McpFilesystemRun.java diff --git a/contrib/samples/mcpfilesystem/README.md b/examples/mcpfilesystem/README.md similarity index 52% rename from contrib/samples/mcpfilesystem/README.md rename to examples/mcpfilesystem/README.md index 5853f355f..a1570c33d 100644 --- a/contrib/samples/mcpfilesystem/README.md +++ b/examples/mcpfilesystem/README.md @@ -1,8 +1,10 @@ # MCP Filesystem Agent Sample -This sample mirrors the `tool_mcp_stdio_file_system_config/root_agent.yaml` configuration by wiring -an MCP filesystem toolset programmatically. The agent launches the filesystem stdio server via -`npx @modelcontextprotocol/server-filesystem` and interacts with it using the Google ADK runtime. +This sample mirrors the `tool_mcp_stdio_file_system_config/root_agent.yaml` +configuration by wiring an MCP filesystem toolset programmatically. The agent +launches the filesystem stdio server via `npx +@modelcontextprotocol/server-filesystem` and interacts with it using the Google +ADK runtime. ## Project Layout @@ -15,17 +17,19 @@ an MCP filesystem toolset programmatically. The agent launches the filesystem st ## Prerequisites -- Java 17+ -- Maven 3.9+ -- Node.js 18+ with `npx` available (for `@modelcontextprotocol/server-filesystem`) +- Java 17+ +- Maven 3.9+ +- Node.js 18+ with `npx` available (for + `@modelcontextprotocol/server-filesystem`) -`npx` downloads the MCP filesystem server on first run. Subsequent executions reuse the cached -package, so expect a longer startup time the first time you run the sample. +`npx` downloads the MCP filesystem server on first run. Subsequent executions +reuse the cached package, so expect a longer startup time the first time you run +the sample. ## Build and Run -Set the Gemini environment variables and launch the interactive session from this directory. One -command compiles and runs the sample: +Set the Gemini environment variables and launch the interactive session from +this directory. One command compiles and runs the sample: ```bash export GOOGLE_GENAI_USE_VERTEXAI=FALSE @@ -33,37 +37,39 @@ export GOOGLE_API_KEY=your_api_key mvn clean compile exec:java ``` -The runner sends an initial prompt asking the agent to list files. To explore additional operations, -reuse the same environment and pass the `--run-extended` argument (you can keep `clean compile` if -you want compilation and execution in a single step): +The runner sends an initial prompt asking the agent to list files. To explore +additional operations, reuse the same environment and pass the `--run-extended` +argument (you can keep `clean compile` if you want compilation and execution in +a single step): ```bash mvn clean compile exec:java -Dexec.args="--run-extended" ``` -If you prefer to launch (and build) the sample while staying in the `google_adk` root, point Maven at -this module’s POM and again use a single command: +If you prefer to launch (and build) the sample while staying in the `google_adk` +root, point Maven at this module’s POM and again use a single command: ```bash export GOOGLE_GENAI_USE_VERTEXAI=FALSE export GOOGLE_API_KEY=your_api_key -mvn -f contrib/samples/mcpfilesystem/pom.xml clean compile exec:java +mvn -f examples/mcpfilesystem/pom.xml clean compile exec:java ``` -To run the extended sequence from the repo root, reuse the same environment variables and pass -`--run-extended`: +To run the extended sequence from the repo root, reuse the same environment +variables and pass `--run-extended`: ```bash export GOOGLE_GENAI_USE_VERTEXAI=FALSE export GOOGLE_API_KEY=your_api_key -mvn -f contrib/samples/mcpfilesystem/pom.xml clean compile exec:java -Dexec.args="--run-extended" +mvn -f examples/mcpfilesystem/pom.xml clean compile exec:java -Dexec.args="--run-extended" ``` The extended flow drives the agent through: -- creating or overwriting `/tmp/mcp-demo/notes.txt` with default content -- reading the file back for confirmation -- searching the workspace for the seeded phrase -- appending a second line and displaying the updated file contents + +- creating or overwriting `/tmp/mcp-demo/notes.txt` with default content +- reading the file back for confirmation +- searching the workspace for the seeded phrase +- appending a second line and displaying the updated file contents ## Related Samples diff --git a/contrib/samples/mcpfilesystem/pom.xml b/examples/mcpfilesystem/pom.xml similarity index 96% rename from contrib/samples/mcpfilesystem/pom.xml rename to examples/mcpfilesystem/pom.xml index 905e0a918..a8d41fe2a 100644 --- a/contrib/samples/mcpfilesystem/pom.xml +++ b/examples/mcpfilesystem/pom.xml @@ -19,9 +19,9 @@ com.google.adk - google-adk-parent + google-adk-examples 1.11.1-SNAPSHOT - ../../.. + .. com.google.adk.samples @@ -29,7 +29,7 @@ Google ADK - Sample - MCP Filesystem Programmatic MCP filesystem sample mirroring the YAML-based configuration under - contrib/samples/configagent. + examples/configagent. jar diff --git a/examples/pom.xml b/examples/pom.xml new file mode 100644 index 000000000..cfb1517a0 --- /dev/null +++ b/examples/pom.xml @@ -0,0 +1,40 @@ + + + + 4.0.0 + + + com.google.adk + google-adk-parent + 1.11.1-SNAPSHOT + .. + + + google-adk-examples + pom + + Google ADK Examples + Aggregator for example applications. + + + a2a_basic + a2a_server + configagent + helloworld + mcpfilesystem + + diff --git a/pom.xml b/pom.xml index 4e5c87851..4e076d448 100644 --- a/pom.xml +++ b/pom.xml @@ -30,9 +30,9 @@ maven_plugin contrib/langchain4j contrib/spring-ai - contrib/samples contrib/planners contrib/firestore-session-service + examples tutorials/city-time-weather tutorials/live-audio-single-agent a2a