feat(tool/openapitoolset): generate tools from an OpenAPI 3.x spec

What

Add a toolset that reads an OpenAPI 3.x document and exposes each operation as an ADK tool, so an agent can call a REST API described by its spec without anyone hand-writing a functiontool per endpoint.

Target import path: google.golang.org/adk/tool/openapitoolset.

Why

adk-python has had this since early on, as google/adk/tools/openapi_tool (openapi_toolset.py, operation_parser.py, rest_api_tool.py). adk-go has no equivalent, so anyone pointing an agent at an existing REST API has to write the wrappers by hand.

#451 attempted it and we closed it: it was stacked on two auth PRs that did not land, and its hand-rolled parser skipped $ref rather than resolving it. The goal here is a much smaller change that reuses what main already provides.

Design constraints

These come from decisions already made in the repo, so a PR that ignores them will not land.

1. Credentials go through auth.CredentialProvider. Main's auth package resolves one credential per invocation and auth.Transport is an http.RoundTripper that applies it per outgoing request. The toolset supplies a provider and an http.Client; it must not build auth headers itself, and it must not reimplement token exchange or refresh. golang.org/x/oauth2 does that.
2. It should be a separate Go module. CONTRIBUTING says integrations with heavy or optional dependencies are separate modules, and an OpenAPI library is one. plugin/agentanalytics is the precedent. This keeps the parser dependency out of the root go.mod, which is what makes the library choice below a low-stakes decision rather than a repo-wide one.
3. The library must resolve $ref. This is the requirement #451 failed. A parameter or request body that references components/schemas has to arrive at the tool declaration fully resolved, otherwise the model receives an untyped argument and the tool call is wrong in a way nothing detects.
4. Operation-level parameters override path-level ones by name and location, per the OpenAPI specification. Appending both lists is a correctness bug.

Decision needed: which library

All three are maintained and permissively licensed. Figures checked on 1 September 2026.

Recommendation: kin-openapi, on the grounds that its loader already meets requirement 3 and it has the widest usage. Whoever picks this up should confirm the resolution behaviour with a spec that uses components/schemas before committing to it.

Scope

In scope:

• Parse an OpenAPI 3.x document from bytes, a file path, or a URL, in JSON or YAML.
• Emit one tool per operation, with a resolved genai.Schema for parameters and request body.
• Path, query, header and cookie parameters, and a JSON request body.
• Execute the call over an injected *http.Client, so auth.Transport supplies credentials.
• Implement tool.Toolset, including Close.
• A filter so callers can select a subset of operations, matching the existing tool.Predicate pattern.

Out of scope for the first PR:

• OAuth2 consent flows. auth handles those.
• Non-JSON request bodies, multipart/form-data, and file upload.
• Response schema validation.

Acceptance

• Table-driven tests over a spec fixture that uses components/schemas, $ref parameters, and both path-level and operation-level parameters.
• A test proving an operation-level parameter overrides a path-level one of the same name and location.
• No live network calls in tests.
• An example under examples/ pointing at a spec served by httptest.

Credit

The idea and a first attempt came from @cpunion in #451. The constraints above are what that PR ran into, not a criticism of it. @cpunion, you are welcome to take this if you would like it.

Start with auth.CredentialProvider and auth.Transport, then inspect plugin/agentanalytics for the separate-module pattern. Confirm kin-openapi resolves internal and external $ref before choosing it, and define the openapitoolset entry points around the injected http.Client and tool.Predicate filter. Done means table-driven fixture tests cover schemas, parameter precedence, no live network calls, and an httptest example is included.