refactor: move the samples from contrib/samples to a top-level examples folder

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",

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.
 

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.

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.

contrib/samples/a2a_basic/pom.xml → examples/a2a_basic/pom.xml

@@ -4,7 +4,7 @@
 
   <parent>
     <groupId>com.google.adk</groupId>
-    <artifactId>google-adk-samples</artifactId>
+    <artifactId>google-adk-examples</artifactId>
     <version>1.11.1-SNAPSHOT</version><!-- {x-version-update:google-adk:current} -->
     <relativePath>..</relativePath>
   </parent>

contrib/samples/a2a_server/README.md → examples/a2a_server/README.md

@@ -39,7 +39,7 @@ GOOGLE_API_KEY before running the service):
 ```bash
 export GOOGLE_API_KEY=<YOUR_API_KEY>
 
-cd contrib/samples/a2a_server
+cd examples/a2a_server
 mvn quarkus:dev
 ```
 

contrib/samples/a2a_server/pom.xml → examples/a2a_server/pom.xml

@@ -4,7 +4,7 @@
 
   <parent>
     <groupId>com.google.adk</groupId>
-    <artifactId>google-adk-samples</artifactId>
+    <artifactId>google-adk-examples</artifactId>
     <version>1.11.1-SNAPSHOT</version><!-- {x-version-update:google-adk:current} -->
     <relativePath>..</relativePath>
   </parent>