mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Shahin Saadati
2570332640
* Add A2A consuming quickstart for Kotlin
adk-kotlin has been able to consume remote A2A agents since 0.6.0, and the docs
had no Kotlin page for it. This adds one alongside the Python, Go and Java
quickstarts, plus its nav entry.
A new page rather than a tab: docs/a2a has no tab groups at all, it is one page
per language, so this follows the section's own shape.
Two dependencies are needed, not one. The a2a artifact publishes the A2A SDK as
runtime-only, and A2AAgent's httpClient parameter defaults to JdkA2AHttpClient(),
so a2a-java-sdk-client has to be on the compile classpath as well. That number
was established by compiling, not by reading module metadata: the a2a artifact
alone fails with "Cannot access class 'A2AHttpClient'", and adding the client
artifact is sufficient -- spec and the jsonrpc transport arrive transitively.
Only the consuming side is documented, because that is all that exists: no
webserver source at v0.7.0 mentions a2a, so there is no Kotlin equivalent of the
exposing quickstarts. The page says so and links to the Python and Java ones.
A2AAgent is a suspending factory, and the implementation class behind it is
internal, so the factory is the only way to construct one. The snippet notes it.
Verified end to end rather than by compiling alone: served a real agent card
from a local server and ran the snippet, which fetched it, parsed it and wired
the remote agent in as a sub-agent --
"Root agent root_agent delegates to prime_agent".
* Correct the agent card claims and make the server step usable
A2AAgent does not read the remote's name from the card: the name is the
caller's, and independent of what the card advertises. It does not read the
transport either, which is hardcoded to JSON-RPC. What the card supplies is
the description and the streaming capability.
The server step told readers to start a server without saying how, and the
two obvious candidates do not work: adk-kotlin parses A2A 1.0 cards, which
require supportedInterfaces with a protocolBinding, and the adk-java and
adk-python samples both publish 0.3-style cards that A2AAgent rejects with
AgentCardResolutionError. State that, and give a minimal card verified by
running the snippet against it.
Also fix the root agent instruction, which referenced dice-rolling the agent
cannot do; match the Java snippet's prime-delegation wording.
* Point the A2A quickstart at the adk-python sample server
The page claimed neither the adk-java nor the adk-python sample works as the
server for this quickstart. The adk-python half is wrong. adk-python does not
serve its `agent.json` verbatim: `fast_api.py` parses it through
`_compat.parse_agent_card`, and under a2a-sdk 1.x that parse promotes the
legacy `url` and `preferredTransport` into `supportedInterfaces`. The dependency
is `a2a-sdk>=0.3.4,<2`, so a fresh install resolves to 1.x and the card on the
wire is A2A 1.0 - exactly what the Kotlin client requires.
So the page now names a server a reader can actually start, instead of asking
them to hand-write a card:
adk api_server --a2a --port 8001 \
contributing/samples/a2a/a2a_basic/remote_a2a
Its card is served under the agent's own prefix, and the snippet's agentCardUrl
follows it to http://localhost:8001/a2a/check_prime_agent. Confirmed the route
prefix in `attach_a2a_routes_to_app` and that the sample card's own `url`
already points there.
The adk-java half of the claim was correct and stays: `a2a_server` is pinned to
the 0.3.x A2A SDK and serves a 0.3 card. That, and the A2A 1.0 requirement it
illustrates, move into a note. The hand-written card survives as a collapsible
fallback for readers bringing their own server.
Reported by joefernandez in review of #2118.