repository·main·Indexed 23 days ago
https://github.com/google/adk-javaA code-first toolkit for building, evaluating, and deploying AI agents integrated with Google Cloud. It features an A2A (Agent-to-Agent) runtime and Spring Boot webservice for JSON-RPC communication, a Firestore session service for scalable user session management, and integrations with LangChain4j for wrapping ChatModels and StreamingChatModels. The kit also includes pluggable planner implementations for orchestrating sub-agents via PlannerAgent.
The Agent Development Kit (ADK) for Java is an open-source, code-first toolkit designed for building, evaluating, and deploying sophisticated AI agents. It is optimized for developers who need fine-grained control and tight integration with Google Cloud services.
Key capabilities include:
The google-adk-planners module provides several strategies for orchestrating sub-agent execution:
| Planner | Package | Execution Model | LLM Required | Primary Use Case |
|---|---|---|---|---|
SequentialPlanner | planner | One at a time, in order | No | Fixed pipelines, ETL steps |
ParallelPlanner | planner | All at once | No | Independent fan-out tasks |
LoopPlanner | planner | Cyclic, repeating | No | Review/revision cycles |
SupervisorPlanner | planner | LLM selects next agent(s) | Yes | Open-ended task delegation |
GoalOrientedPlanner | planner.goap | Dependency-resolved groups | No | Workflows with input/output contracts |
P2PPlanner | planner.p2p | Reactive dynamic activation | No | Collaborative refinement loops |
The Hello World sample is structured as follows:
HelloWorldAgent.java: Contains the agent definition and tool wiring.HelloWorldRun.java: The console runner entry point.pom.xml: Maven configuration specifying the exec main class.README.md: Documentation for the sample.The A2A Basic Sample consists of several key components that illustrate the integration between local tools and remote agents:
A2AAgent.java: This file builds a root agent. The root agent is configured with a local dice-rolling tool and a RemoteA2AAgent which acts as a sub-agent for remote prime-checking.A2AAgentRun.java: A minimal driver class used to execute a single SendMessage turn, demonstrating how the remote call is triggered and handled.pom.xml: The standalone Maven configuration required to build and run this specific sample.The P2P planner (com.google.adk.planner.p2p) is designed for collaborative, iterative workflows where agents react to changes in session state. Unlike GOAP, it does not compute a plan upfront. Instead, agents activate dynamically when their required inputKeys appear in the state.
Key behaviors:
Objects.equals()), downstream agents that depend on that key are re-activated.Use this planner when you need a 'research collaboration' pattern where a critic's feedback triggers a re-run of a hypothesis agent.
List<AgentMetadata> metadata = List.of(
new AgentMetadata("literature", ImmutableList.of("topic"), "researchFindings"),
new AgentMetadata("hypothesis", ImmutableList.of("topic", "researchFindings"), "hypothesis"),
new AgentMetadata("critic", ImmutableList.of("topic", "hypothesis"), "critique"),
new AgentMetadata("scorer", ImmutableList.of("topic", "hypothesis", "critique"), "score")
);
// Exit when score is high enough
P2PPlanner planner = new P2PPlanner(metadata, 20,
(state, count) -> {
Object score = state.get("score");
return score instanceof Number && ((Number) score).doubleValue() >= 0.85;
});
PlannerAgent agent = PlannerAgent.builder()
.name("research")
.subAgents(literatureAgent, hypothesisAgent, criticAgent, scorerAgent)
.planner(planner)
.build();The GOAP subsystem (com.google.adk.planner.goap) resolves agent execution order by analyzing input/output dependencies. Instead of manual sequencing, you define what state keys each agent reads (inputKeys) and writes (outputKey). The planner then computes a dependency graph to determine which agents can run in parallel and in what order to reach a target goal.
To use GOAP, you must define AgentMetadata for each sub-agent and then initialize a GoalOrientedPlanner with your target goal and the metadata list.
List<AgentMetadata> metadata = List.of(
new AgentMetadata("personExtractor", ImmutableList.of("prompt"), "person"),
new AgentMetadata("signExtractor", ImmutableList.of("prompt"), "sign"),
new AgentMetadata("horoscopeGen", ImmutableList.of("person", "sign"), "horoscope"),
new AgentMetadata("writer", ImmutableList.of("person", "horoscope"), "writeup")
);
// Goal is to produce "writeup"
GoalOrientedPlanner planner = new GoalOrientedPlanner("writeup", metadata);
PlannerAgent agent = PlannerAgent.builder()
.name("horoscope")
.subAgents(personExtractor, signExtractor, horoscopeGen, writer)
.planner(planner)
.build();Code located in the contrib/ directory does not have backwards API compatibility guarantees. This applies even across minor (patch) releases.
Maintainers may merge changes to both implementations and interfaces without concern for API stability. This policy is intended to allow contributors to raise PRs and incrementally improve code without the overhead of maintaining strict API stability.
ADK produces a hierarchical trace structure. A standard interaction follows this pattern:
invocation
└── invoke_agent my_agent
├── call_llm
│ ├── tool_call [search_flights]
│ └── tool_response [search_flights]
└── call_llmWhen using Nested Agents (where one agent uses the transfer_to_agent tool to call another), the sub-agent's invocation appears as a child of the parent agent's invocation:
invocation
└── invoke_agent AgentA
├── call_llm
│ ├── tool_call [transfer_to_agent]
│ └── tool_response [transfer_to_agent]
└── invoke_agent AgentB
├── call_llm
└── ...The agent uses a Unified History Trace (reconstructed via GraphQL) to classify the last actor of an issue as an author, maintainer, or other_user. It then follows this decision logic:
| Last actor | Verdict & Action |
|---|---|
| Author / other user | ACTIVE: Remove stale label. If the author silently edited the description, post a one-time maintainer alert. |
| Maintainer (asked question) | STALE: If days_since_activity > threshold, comment + add stale label (and request clarification if missing). |
Issue already stale | CLOSE: If days_since_stale_label > close threshold, comment + close as not planned. |
| Maintainer (status update) | ACTIVE: No action. |
Thresholds default to 7 days for both stale and close actions but are configurable via environment variables.