diff --git a/docs/develop/java/index.mdx b/docs/develop/java/index.mdx index 8e2b0ada49..de77fdf3aa 100644 --- a/docs/develop/java/index.mdx +++ b/docs/develop/java/index.mdx @@ -84,6 +84,7 @@ From there, you can dive deeper into any of the Temporal primitives to start bui ## [Integrations](/develop/java/integrations) +- [Google ADK integration](/develop/java/integrations/google-adk) - [Parseable integration](https://github.com/parseablehq/temporal-plugin-java/blob/main/INTEGRATION.md) - [Spring AI integration](/develop/java/integrations/spring-ai) - [Spring Boot integration](/develop/java/integrations/spring-boot-integration) diff --git a/docs/develop/java/integrations/google-adk.mdx b/docs/develop/java/integrations/google-adk.mdx new file mode 100644 index 0000000000..a9748c58b6 --- /dev/null +++ b/docs/develop/java/integrations/google-adk.mdx @@ -0,0 +1,801 @@ +--- +id: google-adk +title: Google ADK integration +sidebar_label: Google ADK +slug: /develop/java/integrations/google-adk +toc_max_heading_level: 2 +tags: + - Google ADK + - Integrations + - AI Frameworks +description: Run Google ADK Java agents in Temporal Workflows with durable conversations, Activity tools, structured output, and resumable tool calls. +--- + +import { ReleaseNoteHeader } from '@site/src/components'; + +The Temporal [Google ADK Java](https://github.com/google/adk-java) integration runs a native ADK agent inside a +Temporal Workflow. The agent's orchestration and session state stay in the Workflow. Each model call and MCP +operation runs as an Activity, so completed calls are recorded in Event History and aren't repeated during replay. + + + APIs and configuration may change before General Availability. + + +Use `TemporalModel` as the agent's model and build its Runner with `TemporalAdk.runnerBuilder()`. The Runner uses +Workflow time, deterministic identifiers, and Workflow threads for ADK's parallel execution. Register +`GoogleAdkPlugin` on the Temporal Client so its Workers inherit the integration's Activities and payload converter. + +The examples come from the [Java ADK samples](https://github.com/temporalio/samples-java/tree/main/googleadk). +Run each scenario with live Gemini or a credential-free offline model. Both modes use the same plugin, Worker +registration, Workflows, Activities, and message paths. The MCP scenario starts the same local Java subprocess in +both modes. + +| Category | Sample | What it demonstrates | +| --- | --- | --- | +| Agent Chat | [chat](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/chat) | Updates return each turn's reply and conversation state survives Continue-As-New. | +| Tools | [tools](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/tools) | A deterministic function runs in the Workflow; a weather observation runs in an Activity. | +| MCP | [mcp](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/mcp) | List and call a bundled stateless stdio server through Activities. | +| Streaming | Unsupported | Plugin 0.1.1 buffers SSE responses until the model Activity completes; it cannot deliver output while the Activity is running. | +| Human in the Loop | [humanintheloop](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/humanintheloop) | A Signal approves or rejects a pending tool call; cancellation ends the wait. | +| Structured Output | [structuredoutput](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/structuredoutput) | Supply an ADK output schema, validate the response, and return a typed result. | +| Multi-Agent | [multiagent](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/multiagent) | ADK schedules two specialist agents' model Activities concurrently. | +| Observability | Unsupported | Native ADK tracing has no replay suppression and can export duplicate spans during replay. | +| Sandboxes | [Limitations](#understand-the-limitations) | Plugin 0.1.1 does not manage agent-facing code execution environments. | + +The suite also includes a [long-running tool](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/longrunning) +that resumes after a callback. Agent Chat is the introductory example. See [the limitations](#understand-the-limitations) +for streaming, native ADK tracing, and agent sandbox support. + +## Install the integration + +The integration requires Java 17 or later, Google ADK Java 1.12.0 or later, and Temporal Java SDK 1.40.0 or later. +The standalone plugin supplies ADK, but your application must supply the Temporal SDK explicitly. The plugin and SDK +are versioned independently. + +Add the [`io.temporal:google-adk`](https://central.sonatype.com/artifact/io.temporal/google-adk) dependency from Maven +Central alongside the SDK. + +**Maven:** + +```xml + + io.temporal + google-adk + 0.1.1 + + + io.temporal + temporal-sdk + 1.40.0 + +``` + +**Gradle:** + +```groovy +implementation 'io.temporal:google-adk:0.1.1' +implementation 'io.temporal:temporal-sdk:1.40.0' +``` + +The samples use a Gradle version constraint that requires SDK 1.40.0 or later within the 1.x series, preferring +1.40.0. Check your dependency resolution if another dependency supplies an older SDK. + +Before running the samples, [set up your local Java development environment](/develop/java/set-up-your-local-java). +Offline mode needs no provider credentials. For live Gemini, set `GOOGLE_API_KEY` in the Worker's environment or +configure the Google GenAI client for Vertex AI. Model credentials stay on the Worker. + +## Run an agent + +Start with Agent Chat. The `message` Update returns the reply to each user message. A `finish` Signal stops new +messages and lets accepted Updates finish. The optional `lastReply` Query inspects the latest completed reply: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/chat/ChatWorkflow.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/chat/ChatWorkflow.java) +```java +@WorkflowInterface +public interface ChatWorkflow { + @WorkflowMethod + String chat(ChatInput input); + + @UpdateMethod + String message(String text); + + @UpdateValidatorMethod(updateName = "message") + void validateMessage(String text); + + @SignalMethod + void finish(); + + @QueryMethod + String lastReply(); +} +``` + + +Build the agent with ADK's `LlmAgent`, use `TemporalModel` for Activity-based model calls, and drive each turn with +`TemporalAdk.run()` and a Runner built by `TemporalAdk.runnerBuilder()`. `@WorkflowInit` restores the session before +message handlers run. A `WorkflowLock` keeps concurrent turns from interleaving on the shared session: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/chat/ChatWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/chat/ChatWorkflowImpl.java) +```java +public class ChatWorkflowImpl implements ChatWorkflow { + private final WorkflowLock turnLock = Workflow.newWorkflowLock(); + private final Runner runner; + private boolean finished; + private String reply; + private int turns; + + @WorkflowInit + public ChatWorkflowImpl(ChatInput input) { + reply = input.lastReply(); + LlmAgent agent = + LlmAgent.builder() + .name("chat_assistant") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction("Answer concisely, remembering the earlier turns in this conversation.") + .build(); + runner = TemporalAdk.runnerBuilder().appName("chat").agent(agent).build(); + if (input.session() != null) { + Sessions.importSession(runner.sessionService(), input.session()); + } + } + + @Override + public String chat(ChatInput input) { + Workflow.await( + () -> + finished || turns >= 3 || (turns > 0 && Workflow.getInfo().isContinueAsNewSuggested())); + Workflow.await(Workflow::isEveryHandlerFinished); + if (!finished) { + Session snapshot = + Sessions.exportSession( + runner.sessionService(), "chat", AgentSupport.USER, AgentSupport.SESSION); + Workflow.continueAsNew(new ChatInput(snapshot, reply)); + } + return reply; + } + + @Override + public String message(String text) { + turnLock.lock(); + try { + reply = + AgentSupport.lastText( + TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Content.fromParts(Part.fromText(text)))); + turns++; + return reply; + } finally { + turnLock.unlock(); + } + } + + @Override + public void validateMessage(String text) { + if (finished) { + throw new IllegalStateException("The conversation is finishing."); + } + if (text == null || text.isBlank()) { + throw new IllegalArgumentException("The message must not be blank."); + } + } + + @Override + public void finish() { + finished = true; + } + + @Override + public String lastReply() { + return reply; + } +} +``` + + +`AgentSupport.MODEL` is `gemini-2.5-flash`; `USER` and `SESSION` identify the ADK user and session within this +Workflow. `lastText` returns the last text response among the turn's events. + +The example uses the provider's model name for both registration and `TemporalModel`. ADK's Workflow-side +capability checks use the `TemporalModel` name. Plugin 0.1.1 resolves registration aliases to the worker-side +provider model name for model calls, while preserving explicit before-model callback overrides. + +On the Worker, register a model factory and a named MCP toolset through `GoogleAdkPlugin`. The sample's `plugin` +helper accepts either a Gemini factory or the offline provider: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/SampleWorker.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/SampleWorker.java) +```java +public static GoogleAdkPlugin plugin(Supplier models) { + return GoogleAdkPlugin.newBuilder() + .model(AgentSupport.MODEL, models) + .mcpToolset("echo", EchoMcpServer::toolset) + .build(); +} + +``` + + +Register the plugin on the Temporal Client so its Workers inherit the model and MCP Activities and payload converter. +The sample reads `ADK_MODEL_MODE` before the following block, defaulting to `live`. It constructs a Gemini client only +in live mode and disables the client's native retries so Temporal owns retries: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/SampleWorker.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/SampleWorker.java) +```java +Client modelClient = + mode.equals("live") + ? Client.builder() + .httpOptions( + HttpOptions.builder() + .retryOptions(HttpRetryOptions.builder().attempts(1).build()) + .build()) + .build() + : null; +GoogleAdkPlugin plugin = + plugin( + modelClient == null + ? OfflineModel::new + : () -> + Gemini.builder().modelName(AgentSupport.MODEL).apiClient(modelClient).build()); +WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs(); +WorkflowClient client = + WorkflowClient.newInstance( + service, WorkflowClientOptions.newBuilder().setPlugins(plugin).build()); +WorkerFactory factory = WorkerFactory.newInstance(client); +Worker worker = factory.newWorker(AgentSupport.TASK_QUEUE); +register(worker); +factory.start(); +``` + + +`register(worker)` hosts all seven scenarios and their Activity implementations. The same registration is used in the +offline tests. The MCP toolset is created on first use; the other scenarios don't start an MCP server. + +Run the following commands from the samples repository root. Start the Temporal development server in one terminal: + +```bash +temporal server start-dev +``` + +Start an offline Worker in a second terminal: + +```bash +ADK_MODEL_MODE=offline ./gradlew :googleadk:worker +``` + +In a third terminal, execute a Workflow on its Task Queue: + +```bash +temporal workflow start --workflow-id adk-chat --type ChatWorkflow --task-queue google-adk-samples --input '{"session":null,"lastReply":""}' +temporal workflow update execute --workflow-id adk-chat --name message --input '"Hello"' +``` + +The Update waits for its own reply. Offline mode returns `turns=1; latest: Hello`. Send more Updates to continue +the conversation, or finish and wait for its result: + +```bash +temporal workflow signal --workflow-id adk-chat --name finish +temporal workflow result --workflow-id adk-chat +``` + +Use a new Workflow ID for another conversation. The scripted provider is limited to these scenarios; weather and +travel examples use fixed Chicago data. It makes no provider requests, but still runs real Temporal Activities. +Offline runs require a running Temporal Service, and the first Gradle build can download dependencies. + +To use Gemini, stop the offline Worker and restart it with live mode: + +```bash +GOOGLE_API_KEY=your_key ADK_MODEL_MODE=live ./gradlew :googleadk:worker +``` + +The Workflow commands and Task Queue remain the same. Inspect model and tool Activities in the Temporal UI at +`http://localhost:8233`. + +To start the same Workflow from Java, register `GoogleAdkPlugin` on the caller's Client too. The existing starter +does this so ADK payload types use the same converter: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/SampleStarter.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/SampleStarter.java) +```java +ChatWorkflow chat = client.newWorkflowStub(ChatWorkflow.class, options); +WorkflowClient.start(chat::chat, ChatInput.empty()); +System.out.println("Workflow ID: " + id); +``` + + +The starter defaults to Agent Chat: run `./gradlew :googleadk:starter` without arguments. Each scenario's README provides +Temporal CLI commands for its inputs, Updates, Signals, Queries, and results. + +`TemporalModel.newBuilder(name).activityOptions(...)` customizes model Activity timeouts and retries. The default +start-to-close timeout is two minutes. A heartbeat timeout enables heartbeats while the model call runs. + +### Validate structured output + +Set an agent's `outputSchema` to constrain the model response. The structured-output sample describes a travel plan +with a city, one to seven days, and a list of activities: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/structuredoutput/StructuredOutputWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/structuredoutput/StructuredOutputWorkflowImpl.java) +```java +private static final Schema PLAN_SCHEMA = + Schema.builder() + .type("OBJECT") + .properties( + Map.of( + "city", Schema.builder().type("STRING").build(), + "days", Schema.builder().type("INTEGER").minimum(1.0).maximum(7.0).build(), + "activities", + Schema.builder() + .type("ARRAY") + .items(Schema.builder().type("STRING").build()) + .minItems(1L) + .build())) + .required(List.of("city", "days", "activities")) + .build(); + +``` + + +Validate the response at the Workflow boundary before returning a typed `TravelPlan`. The sample rejects malformed +JSON and trailing values, checks field types against ADK's schema, and validates the record's values: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/structuredoutput/StructuredOutputWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/structuredoutput/StructuredOutputWorkflowImpl.java) +```java +@Override +public TravelPlan plan(String request) { + LlmAgent agent = + LlmAgent.builder() + .name("structured_planner") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction( + "Return a travel plan as JSON with city, days (1 through 7), and activities.") + .outputSchema(PLAN_SCHEMA) + .build(); + Runner runner = TemporalAdk.runnerBuilder().appName("structured_plan").agent(agent).build(); + String json = + AgentSupport.lastText( + TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Content.fromParts(Part.fromText(request)))); + try { + ObjectMapper mapper = + new ObjectMapper().enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS); + Map output = mapper.readValue(json, new TypeReference<>() {}); + if (output == null) { + throw new IllegalArgumentException("A plan must be a JSON object."); + } + SchemaUtils.validateMapOnSchema(output, PLAN_SCHEMA, false); + return mapper.convertValue(output, TravelPlan.class); + } catch (JsonProcessingException | IllegalArgumentException e) { + throw ApplicationFailure.newNonRetryableFailure( + "The model did not return a valid travel plan.", "InvalidTravelPlan"); + } +} +``` + + +`TravelPlan` requires a nonblank city, one to seven days, and at least one nonblank activity. Invalid model output +fails the Workflow with a non-retryable `InvalidTravelPlan` failure. This prevents invalid output from repeatedly +failing a Workflow Task. + +With either Worker mode running, execute the sample: + +```bash +temporal workflow execute --type StructuredOutputWorkflow --task-queue google-adk-samples --input '"Plan two days in Chicago."' +``` + +Offline mode returns a two-day Chicago plan with a lakefront walk and a museum visit. Live Gemini supplies its own +plan with the same schema. The model call is an Activity; validation and the typed return value stay in the Workflow. + +## Expose tools as Activities + +Plain ADK function tools run on the Workflow thread. Use them for deterministic operations on agent or Workflow +state. Put network, file, and other I/O in a Temporal Activity and expose the Activity stub with `ActivityTools.create`. + +Declare the tool's schema on the Activity interface: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/tools/WeatherActivities.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/tools/WeatherActivities.java) +```java +@ActivityInterface +public interface WeatherActivities { + @ActivityMethod(name = "GetWeather") + Map getWeather( + @Schema(name = "city", description = "The city to look up") String city); +} +``` + + +Define a deterministic function tool for calculations that need no I/O: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/tools/TemperatureTools.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/tools/TemperatureTools.java) +```java +public static Map toFahrenheit( + @Schema(name = "celsius", description = "Temperature in degrees Celsius") double celsius) { + return Map.of("fahrenheit", celsius * 9 / 5 + 32); +} +``` + + +Supply both the Activity stub and the function as ADK tools: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/tools/ToolsWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/tools/ToolsWorkflowImpl.java) +```java +@Override +public String ask(String question) { + WeatherActivities weather = + Workflow.newActivityStub( + WeatherActivities.class, + ActivityOptions.newBuilder() + .setStartToCloseTimeout(Duration.ofSeconds(30)) + .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(3).build()) + .build()); + LlmAgent agent = + LlmAgent.builder() + .name("weather_assistant") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction( + "Use getWeather for conditions and Celsius temperature, then toFahrenheit to" + + " convert the temperature. Report the conditions and both temperatures.") + .tools( + ActivityTools.create(weather, "getWeather"), + FunctionTool.create(TemperatureTools.class, "toFahrenheit")) + .build(); + Runner runner = TemporalAdk.runnerBuilder().appName("tools").agent(agent).build(); + return AgentSupport.lastText( + TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Content.fromParts(Part.fromText(question)))); +} +``` + + +`getWeather` runs as the `GetWeather` Activity with the stub's timeout and retry policy. Its result returns to the +agent as a function response. `toFahrenheit` runs directly on the Workflow thread and schedules no Activity. +If the weather Activity exhausts its retries or returns a non-retryable failure, `ActivityFailure` propagates to the +Workflow. + +Every parameter needs `@Schema(name = ...)` unless the Activity interface is compiled with `-parameters`. The +[tools sample](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/tools) +returns illustrative weather data and reads `Instant.now()` inside the Activity. The host timestamp demonstrates +why the observation needs an Activity. Replace that implementation with your provider's HTTP call for real weather. + +### Resume a long-running tool + +Use `ActivityTools.createLongRunning` when a tool starts an operation whose result will arrive later. The report +sample submits a job as an Activity and returns a pending status: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/longrunning/ReportActivities.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/longrunning/ReportActivities.java) +```java +@ActivityInterface +public interface ReportActivities { + @ActivityMethod(name = "StartReport") + Map startReport( + @Schema(name = "name", description = "The report to prepare") String name); +} +``` + + +After the ADK turn, use `Hitl.longRunningCalls` to find the pending function call. Wait for its result through a +Signal, then resume the original call with `Hitl.functionResponse`: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/longrunning/LongRunningWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/longrunning/LongRunningWorkflowImpl.java) +```java +@Override +public String prepare(String request) { + ReportActivities reports = + Workflow.newActivityStub( + ReportActivities.class, + ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(30)).build()); + LlmAgent agent = + LlmAgent.builder() + .name("report_assistant") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction("Start exactly one report with startReport. Wait for its final result.") + .tools(ActivityTools.createLongRunning(reports, "startReport")) + .build(); + Runner runner = TemporalAdk.runnerBuilder().appName("reports").agent(agent).build(); + List events = + TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Content.fromParts(Part.fromText(request))); + List pending = Hitl.longRunningCalls(events); + if (pending.size() != 1) { + throw ApplicationFailure.newNonRetryableFailure( + "Expected exactly one pending report.", "InvalidReportRequest"); + } + FunctionCall call = pending.get(0); + callId = call.id().orElseThrow(); + Workflow.await(() -> result != null); + events = + TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Hitl.functionResponse(call, Map.of("status", "done", "result", result))); + callId = ""; + return AgentSupport.lastText(events); +} + +``` + + +The sample's `pendingCall` Query returns the function-call identifier. Its `complete` Signal accepts that identifier +and a result. Start a report and query the pending call: + +```bash +temporal workflow start --workflow-id adk-report --type LongRunningWorkflow --task-queue google-adk-samples --input '"Prepare a sales report."' +temporal workflow query --workflow-id adk-report --name pendingCall +``` + +Repeat the Query until the identifier is nonempty. Replace `CALL_ID` with that value before sending the callback: + +```bash +temporal workflow signal --workflow-id adk-report --name complete --input '"CALL_ID"' --input '"Revenue grew 10%."' +temporal workflow result --workflow-id adk-report +``` + +While waiting, the Signal handler ignores premature callbacks and wrong identifiers; the first matching result wins. +Offline mode returns `Report complete: Revenue grew 10%.`. + +The Activity simulates report submission. The Workflow's wait needs no polling Activity or open model connection, +and replay does not submit the report again. Use a new Workflow ID for another run. A real report service must store +the callback correlation and send the Signal when its work finishes. + +### Use MCP tools + +Register a worker-side ADK `McpToolset` under a name, as the Worker example does with `echo`. Reference that name +in the Workflow with `TemporalMcpToolset`: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/mcp/McpWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/mcp/McpWorkflowImpl.java) +```java +@Override +public String echo(String message) { + LlmAgent agent = + LlmAgent.builder() + .name("echo_assistant") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction("Call echo with the user's message, then return the echoed text.") + .tools(TemporalMcpToolset.newBuilder("echo").cacheTools(true).build()) + .build(); + Runner runner = TemporalAdk.runnerBuilder().appName("echo").agent(agent).build(); + return AgentSupport.lastText( + TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Content.fromParts(Part.fromText(message)))); +} +``` + + +The Workflow never connects to the MCP server. Listing tools runs the `googleadk.ListMcpTools` Activity, and calling +one runs `googleadk.CallMcpTool`. By default, tools are listed before each model call; `cacheTools(true)` lists them +once per Workflow Execution. The Worker caches the toolset and closes it during shutdown after in-flight calls finish. + +The [MCP sample](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/mcp) +includes a local Java stdio echo server. No Node installation or separately running MCP service is needed. + +## Run multiple agents + +ADK's `ParallelAgent` works with the Workflow scheduler supplied by `TemporalAdk.runnerBuilder()`. Its sub-agents +schedule model Activities concurrently while their orchestration stays on Workflow threads: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/multiagent/MultiAgentWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/multiagent/MultiAgentWorkflowImpl.java) +```java +@Override +public List plan(String question) { + LlmAgent planner = + LlmAgent.builder() + .name("planner") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction("Propose a short travel itinerary for the user's destination.") + .build(); + LlmAgent reviewer = + LlmAgent.builder() + .name("reviewer") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction("List practical travel considerations for the user's destination.") + .build(); + ParallelAgent root = + ParallelAgent.builder().name("travel_team").subAgents(planner, reviewer).build(); + // The runner supplies workflow threads for ADK's parallel fan-out. + Runner runner = TemporalAdk.runnerBuilder().appName("travel").agent(root).build(); + return TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Content.fromParts(Part.fromText(question))) + .stream() + .flatMap(event -> event.content().stream()) + .map(Content::text) + .filter(text -> text != null && !text.isEmpty()) + .sorted() + .toList(); +} +``` + + +Do not override a `ParallelAgent` scheduler or an `LlmAgent` executor: agent-level settings override the Runner's +scheduler and move execution off Workflow threads. For sequential execution, pass `WorkflowScheduler.sequential()` +to `TemporalAdk.runnerBuilder(...)`. + +## Wait for human approval + +Pass `true` as the confirmation argument to `ActivityTools.create` to pause before the tool executes. Read pending +requests with `Hitl.pendingConfirmations`, wait for a Signal, and resume the next ADK turn with +`Hitl.confirmationResponse`: + + +[googleadk/src/main/java/io/temporal/samples/googleadk/humanintheloop/ApprovalWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/main/java/io/temporal/samples/googleadk/humanintheloop/ApprovalWorkflowImpl.java) +```java +@Override +public String fulfill(String question) { + OrderActivities orders = + Workflow.newActivityStub( + OrderActivities.class, + ActivityOptions.newBuilder() + .setStartToCloseTimeout(Duration.ofSeconds(30)) + .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(3).build()) + .build()); + LlmAgent agent = + LlmAgent.builder() + .name("fulfillment_assistant") + .model(TemporalModel.create(AgentSupport.MODEL)) + .instruction( + "Use shipOrder when asked to ship an order. Respect rejected confirmations.") + .tools(ActivityTools.create(orders, "shipOrder", true)) + .build(); + Runner runner = TemporalAdk.runnerBuilder().appName("approval").agent(agent).build(); + List events = + TemporalAdk.run( + runner, + AgentSupport.USER, + AgentSupport.SESSION, + Content.fromParts(Part.fromText(question))); + pending = Hitl.pendingConfirmations(events); + while (!pending.isEmpty()) { + Workflow.await(() -> decision != null); + Content response = + Hitl.confirmationResponse( + pending.stream() + .map(p -> new Hitl.ConfirmationDecision(p.functionCallId(), decision)) + .toArray(Hitl.ConfirmationDecision[]::new)); + decision = null; + pending = List.of(); + events = TemporalAdk.run(runner, AgentSupport.USER, AgentSupport.SESSION, response); + pending = Hitl.pendingConfirmations(events); + } + return AgentSupport.lastText(events); +} + +``` + + +The [approval sample](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/humanintheloop) +exposes pending tool names and arguments through a Query. A Signal handler sets `decision`. The example applies +that decision to all pending calls from the turn. A confirmed call schedules the shipping Activity; a rejected call +does not. The sample Activity returns mock shipment data and makes no fulfillment request. + +Use the Temporal CLI to start and query an approval Workflow: + +```bash +temporal workflow start --workflow-id adk-approval --type ApprovalWorkflow --task-queue google-adk-samples --input '"Ship order demo-order, after confirmation."' +temporal workflow query --workflow-id adk-approval --name pendingConfirmations +``` + +Repeat the Query until a pending request appears. Then send a decision and wait for the result: + +```bash +temporal workflow signal --workflow-id adk-approval --name decide --input true +temporal workflow result --workflow-id adk-approval +``` + +Use `--input false` to reject a pending request on a fresh execution. Premature Signals are ignored, and the first +decision for the pending batch wins. Offline results are `Order shipped.` and `Order rejected.`. To cancel the wait +instead, run `temporal workflow cancel --workflow-id adk-approval`. A cancellation before approval schedules no +shipping Activity. + +## Preserve conversations through Continue-As-New + +The Agent Chat example above keeps the Runner's session service in the Workflow; replay rebuilds it from Event History. A new Run after +[Continue-As-New](/develop/java/workflows/continue-as-new) starts with an empty session service. Export the ADK session with +`Sessions.exportSession`, carry it in the next Run's input, and restore it with `Sessions.importSession`. + +The [chat sample](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/chat) +serializes message Updates on the shared ADK session. After three completed turns, or when Temporal suggests +Continue-As-New, the main Workflow waits for `Workflow.isEveryHandlerFinished()`, exports the session, and carries +the snapshot and last reply into the next Run. `@WorkflowInit` imports the snapshot before Update handlers run. +Continue-As-New runs in the main Workflow method after accepted Updates finish. A `finish` Signal rejects new +messages, drains accepted Updates, and completes the Workflow. + +Use the [chat README](https://github.com/temporalio/samples-java/tree/main/googleadk/src/main/java/io/temporal/samples/googleadk/chat) +for the Update and finish commands. Offline replies show the conversation's turn count, including turns restored +after Continue-As-New. Live Gemini receives the imported conversation as context. + +The snapshot preserves session-scoped state and events, including pending confirmations. It does not carry app-, +user-, or temporary-scoped state. Continue-As-New limits each Run's Event History; the conversation snapshot still +grows and must remain within Temporal's [payload limits](/evaluate/cloud/limits#transaction-payload-size-limit). + +## Test and replay without credentials + +Use `io.temporal.googleadk.testing.ScriptedModel` as the worker-side model in `TestWorkflowEnvironment`. Configure +the test environment's Client with the same plugin as a live Worker, then replay the recorded history on a fresh +Worker: + + +[googleadk/src/test/java/io/temporal/samples/googleadk/ChatWorkflowTest.java](https://github.com/temporalio/samples-java/blob/main/googleadk/src/test/java/io/temporal/samples/googleadk/ChatWorkflowTest.java) +```java +ScriptedModel model = + ScriptedModel.of( + AgentSupport.MODEL, + ScriptedModel.text("First reply"), + ScriptedModel.text("Last reply")); +try (AdkTestEnvironment test = new AdkTestEnvironment(model, ChatWorkflowImpl.class)) { + test.environment.start(); + ChatWorkflow workflow = test.workflow(ChatWorkflow.class); + WorkflowClient.start(workflow::chat, ChatInput.empty()); + + assertEquals("First reply", workflow.message("one")); + assertEquals("Last reply", workflow.message("two")); + workflow.finish(); + assertEquals("Last reply", WorkflowStub.fromTyped(workflow).getResult(String.class)); + assertEquals(2, model.requests().size()); + test.replay(test.history(workflow), ChatWorkflowImpl.class); +} +``` + + +The [test helper](https://github.com/temporalio/samples-java/blob/main/googleadk/src/test/java/io/temporal/samples/googleadk/AdkTestEnvironment.java) +registers the plugin through `TestEnvironmentOptions.setWorkflowClientOptions`. Its replay check creates another +Worker with the plugin, replays the history, and verifies the model received no additional requests. + +Run the suite without provider credentials or an external Temporal Service: + +```bash +./gradlew :googleadk:test :googleadk:spotlessCheck :googleadk:build +``` + +The tests verify Activity retries and non-retryable failures, deterministic function results, parallel model +scheduling, a real local MCP server, approval/rejection and cancellation, invalid structured output, correlated +callbacks, concurrent Update replies, shutdown with accepted Updates, and session recovery through Continue-As-New. +`OfflineSamplesTest` also runs every scenario with the same `OfflineModel` and `SampleWorker.register` used by the +runnable Worker. Each scenario's README includes a targeted test command. + +## Understand the limitations + +- In version 0.1.1, streamed model chunks reach the Workflow after the model Activity completes. Delivery through + Workflow Streams while the Activity is running is tracked in [#257](https://github.com/temporalio/ai-integrations/issues/257). + Live bidirectional connections are also unsupported. +- ADK services that perform I/O, including code execution, memory, and artifact services, cannot run directly inside + a Workflow. Use Activities for I/O. The plugin does not durably manage an agent-facing code execution environment. +- Avoid RxJava blocking methods inside a Workflow. Use `TemporalAdk.run` or `TemporalAdk.await` so the Workflow + thread yields while Activities or timers are pending. +- ADK uses global OpenTelemetry providers. The plugin has no replay suppression for ADK tracing, so an installed + tracing SDK emits duplicate spans during replay. Replay-safe native ADK tracing is tracked in + [#258](https://github.com/temporalio/ai-integrations/issues/258). +- Canceling an approval or callback wait does not undo a shipment or cancel an external job that already started. + A real backend needs an explicit cancellation Activity. +- ADK's experimental App resumability and event compaction are not covered by the integration's tests. +- Gemini context caching is inactive because its cache configuration does not cross the Activity boundary. + +See the [integration README](https://github.com/temporalio/ai-integrations/tree/main/java/google-adk) for the complete +API, payload converter configuration, and failure classification. diff --git a/docs/develop/plugins-guide.mdx b/docs/develop/plugins-guide.mdx index 6fc5968a85..8890bf78a7 100644 --- a/docs/develop/plugins-guide.mdx +++ b/docs/develop/plugins-guide.mdx @@ -43,6 +43,7 @@ If you prefer to learn by getting hands-on with code, check out some existing pl - [Temporal client and Worker plugin for Pydantic AI](https://github.com/pydantic/pydantic-ai/blob/d9b4b2540183a4426669b2824c87cdfc36144780/pydantic_ai_slim/pydantic_ai/durable_exec/temporal/__init__.py#L142) - Temporal's TypeScript SDK ships with an [OpenTelemetry Plugin](https://github.com/temporalio/sdk-typescript/blob/main/contrib/interceptors-opentelemetry/src/plugin.ts) +- Temporal maintains a [Google ADK plugin for Java](/develop/java/integrations/google-adk) in Public Preview ## What you can provide to users in a plugin diff --git a/sidebars.js b/sidebars.js index 50ff0e2984..166a308d2f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -495,7 +495,11 @@ const developJavaCategory = { type: 'doc', id: 'develop/java/integrations/index', }, - items: ['develop/java/integrations/spring-boot', 'develop/java/integrations/spring-ai'], + items: [ + 'develop/java/integrations/google-adk', + 'develop/java/integrations/spring-boot', + 'develop/java/integrations/spring-ai', + ], }, ], }; diff --git a/src/components/IntegrationsGrid/integrations-data.json b/src/components/IntegrationsGrid/integrations-data.json index 1678261d77..1970503294 100644 --- a/src/components/IntegrationsGrid/integrations-data.json +++ b/src/components/IntegrationsGrid/integrations-data.json @@ -98,6 +98,15 @@ "sdk": "Go", "href": "/develop/go/integrations/google-adk" }, + { + "name": "Google ADK", + "description": "Run Google ADK Java agents with durable conversations, tools, and structured output. Public Preview.", + "tags": [ + "Agent framework" + ], + "sdk": "Java", + "href": "/develop/java/integrations/google-adk" + }, { "name": "Google ADK", "description": "Run Google ADK agents as durable Temporal Workflows.",