@google/adk 2.0.0 → 2.2.0

package/dist/types/tools/function_tool.d.ts

@@ -29,11 +29,31 @@ export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (inpu
 export type RequireConfirmation<TParameters extends ToolInputParameters> = boolean | ((input: ToolExecuteArgument<TParameters>, toolContext?: Context) => boolean | Promise<boolean>);
 /**
  * The configuration options for creating a function-based tool.
- * The `name`, `description` and `parameters` fields are used to generate the
- * tool definition that is passed to the LLM prompt.
  *
- * Note: Unlike Python's ADK, JSDoc on the `execute` function is ignored
- * for tool definition generation.
+ * What the model is shown about the tool is built from these options: `name`,
+ * `description` and the `parameters` schema become its function declaration.
+ * TypeScript types and JSDoc are erased at runtime and cannot be read back, so
+ * `description` is required and per-argument descriptions have to live in the
+ * schema — typically as Zod `.describe()` calls.
+ *
+ * ```ts
+ * new FunctionTool({
+ *   name: 'get_weather',
+ *   description: 'Returns the current weather for a city.',
+ *   parameters: z.object({
+ *     city: z.string().describe('City name, e.g. "San Francisco".'),
+ *   }),
+ *   execute: async ({city}) => fetchWeather(city),
+ * });
+ * ```
+ *
+ * A subclass may add to the declaration it derives from these options: given
+ * the identical options, {@link LongRunningFunctionTool} appends a sentence to
+ * `description` telling the model not to re-invoke a call that is still in
+ * flight.
+ *
+ * `parameters` is a description for the model, and only a Zod object schema is
+ * additionally enforced at call time — see {@link FunctionTool.runAsync}.
  */
 export type ToolOptions<TParameters extends ToolInputParameters> = {
     name?: string;
@@ -74,10 +94,20 @@ export declare function isFunctionTool(obj: unknown): obj is FunctionTool;
 /**
  * A tool that wraps a user-defined function, making it callable by an LLM.
  *
- * The function's name, description, and parameter schema are exposed to the
+ * The tool's name, description, and parameter schema are exposed to the
  * model as a function declaration. When the model requests a call, the
- * framework validates the arguments and invokes the user-provided `execute`
- * callback.
+ * framework invokes the user-provided `execute` callback with the arguments
+ * the model produced.
+ *
+ * Those arguments are checked only when `parameters` is a Zod object schema:
+ * it is applied with `parse()`, so a call that does not match is rejected and
+ * `execute` receives the parsed value. Keys the schema does not declare are
+ * handled however that schema says: a plain `z.object()` drops them,
+ * `.passthrough()` forwards them, `.strict()` rejects the call. A plain
+ * genai `Schema`, or no `parameters` at all, is shown to the model but is not
+ * a runtime guard — the arguments reach `execute` exactly as the model
+ * produced them, wrong types and extra keys included. Validate them inside
+ * `execute` on that path.
  */
 export declare class FunctionTool<TParameters extends ToolInputParameters = undefined> extends BaseTool {
     /** A unique symbol to identify ADK function tool class. */
@@ -96,11 +126,14 @@ export declare class FunctionTool<TParameters extends ToolInputParameters = unde
      */
     _getDeclaration(): FunctionDeclaration;
     /**
-     * Validates the model-provided arguments against the parameter schema and
-     * invokes the user-defined `execute` function.
+     * Invokes the user-defined `execute` function with the model-provided
+     * arguments, after parsing them when `parameters` is a Zod object schema.
+     * Any other `parameters` value is passed through unchecked.
      *
      * @param req The tool request containing arguments and tool context.
      * @returns A promise resolving to the function's return value.
+     * @throws {Error} Wrapped as `Error in tool '<name>': …` when a Zod
+     *     `parameters` schema rejects the arguments or `execute` throws.
      */
     runAsync(req: RunAsyncToolRequest): Promise<unknown>;
     /**

package/dist/types/tools/google_maps_grounding_tool.d.ts

@@ -1,5 +1,6 @@
 import { LlmRequest } from '../models/llm_request.js';
-import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+import { ToolProcessLlmRequest } from './base_tool.js';
+import { BuiltInTool } from './built_in_tool.js';
 /**
  * Applies Google Maps grounding to the LLM request if supported.
  */
@@ -11,10 +12,9 @@ export declare function applyGoogleMapsGrounding(llmRequest: LlmRequest): void;
  * This tool operates internally within the model and does not require or
  * perform local code execution.
  */
-export declare class GoogleMapsGroundingTool extends BaseTool {
+export declare class GoogleMapsGroundingTool extends BuiltInTool {
     constructor();
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+    protected applyBuiltInConfig({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }
 /**
  * A global instance of {@link GoogleMapsGroundingTool}.

package/dist/types/tools/google_search_tool.d.ts

@@ -1,4 +1,5 @@
-import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+import { ToolProcessLlmRequest } from './base_tool.js';
+import { BuiltInTool } from './built_in_tool.js';
 /**
  * A built-in tool that is automatically invoked by Gemini 2 models to retrieve
  * search results from Google Search.
@@ -6,10 +7,9 @@ import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
  * This tool operates internally within the model and does not require or
  * perform local code execution.
  */
-export declare class GoogleSearchTool extends BaseTool {
+export declare class GoogleSearchTool extends BuiltInTool {
     constructor();
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+    protected applyBuiltInConfig({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }
 /**
  * A global instance of {@link GoogleSearchTool}.

package/dist/types/tools/long_running_tool.d.ts

@@ -10,7 +10,7 @@ import { FunctionTool, ToolInputParameters, ToolOptions } from './function_tool.
  * asynchronously.
  *
  * The framework invokes the user-provided function and delivers the response
- * back to the model once it completes, identified by the `function_call_id`.
+ * back to the model once it completes, matched up by the function call's `id`.
  * The model is also instructed not to re-invoke the tool while a call is
  * already in flight.
  */

package/dist/types/tools/mcp/mcp_toolset.d.ts

@@ -24,18 +24,19 @@ import { MCPConnectionParams } from './mcp_session_manager.js';
  * LLM invokes the prefixed tool, this toolset transparently strips the prefix
  * before sending the request to the underlying MCP server.
  *
- * Usage:
- *   import { MCPToolset } from '@google/adk';
- *   import { StreamableHTTPConnectionParamsSchema } from '@google/adk';
+ * @example
+ * ```ts
+ * import {MCPToolset} from '@google/adk';
+ * import type {StreamableHTTPConnectionParams} from '@google/adk';
  *
- *   const connectionParams = StreamableHTTPConnectionParamsSchema.parse({
- *     type: "StreamableHTTPConnectionParams",
- *     url: "http://localhost:8788/mcp"
- *   });
- *
- *   const mcpToolset = new MCPToolset(connectionParams);
- *   const tools = await mcpToolset.getTools();
+ * const connectionParams: StreamableHTTPConnectionParams = {
+ *   type: 'StreamableHTTPConnectionParams',
+ *   url: 'http://localhost:8788/mcp',
+ * };
  *
+ * const mcpToolset = new MCPToolset(connectionParams);
+ * const tools = await mcpToolset.getTools();
+ * ```
  */
 export declare class MCPToolset extends BaseToolset {
     private readonly mcpSessionManager;

package/dist/types/tools/openapi_tool/auth/auth_helpers.d.ts

@@ -4,15 +4,27 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { OpenAPIV3 } from 'openapi-types';
-import { AuthCredential } from '../../../auth/auth_credential.js';
+import { AuthCredential, ServiceAccount } from '../../../auth/auth_credential.js';
+import { AuthScheme, OpenIdConnectWithConfig } from '../../../auth/auth_schemes.js';
+import { ApiParameter } from '../openapi_spec_parser/operation_parser.js';
+/**
+ * Prefix that marks a tool parameter as auth-injected rather than
+ * model-supplied.
+ */
+export declare const INTERNAL_AUTH_PREFIX = "_auth_prefix_vaf_";
 /**
  * Applies the given credential to the request headers and URL.
  *
+ * An HTTP credential that carries no usable token throws, so the caller never
+ * sends an unauthenticated request in place of an authenticated one.
+ *
  * @param url The target URL.
  * @param headers The request headers.
  * @param credential The auth credential.
  * @param authScheme The auth scheme from OpenAPI spec.
  * @returns The updated URL (if modified by query params).
+ * @throws {Error} If an HTTP credential holds basic credentials, or holds no
+ *   credentials at all.
  */
 export declare function applyCredential(url: string, headers: Record<string, string>, credential?: AuthCredential, authScheme?: OpenAPIV3.SecuritySchemeObject): string;
 /**
@@ -23,3 +35,105 @@ export declare function createApiKeyScheme(name: string, inLocation: 'header' |
  * Helper to create a simple Bearer Token auth scheme.
  */
 export declare function createBearerScheme(): OpenAPIV3.SecuritySchemeObject;
+/**
+ * Creates an AuthScheme and AuthCredential for an API key or a bearer token.
+ *
+ * @example
+ * // API key in a header.
+ * const [scheme, credential] = tokenToSchemeCredential(
+ *   'apikey', 'header', 'X-API-Key', 'your_api_key_value');
+ *
+ * @example
+ * // OAuth2 bearer token in the Authorization header.
+ * const [scheme, credential] = tokenToSchemeCredential(
+ *   'oauth2Token', 'header', 'Authorization', 'your_bearer_token_value');
+ *
+ * @param tokenType `'apikey'` or `'oauth2Token'`.
+ * @param location Where the API key travels. Ignored for `'oauth2Token'`,
+ *   because a bearer token always travels in the Authorization header.
+ * @param name The name of the header, query parameter, or cookie.
+ * @param credentialValue The API key or token value. Omit it to build the
+ *   scheme alone.
+ * @returns A `[scheme, credential]` pair. The credential is `undefined` when
+ *   `credentialValue` is omitted.
+ * @throws Error For an unsupported token type or API key location.
+ */
+export declare function tokenToSchemeCredential(tokenType: 'apikey' | 'oauth2Token', location?: 'header' | 'query' | 'cookie', name?: string, credentialValue?: string): [AuthScheme, AuthCredential | undefined];
+/**
+ * Creates a bearer scheme and a service-account credential from a raw Google
+ * service-account JSON object.
+ *
+ * @param config The parsed service-account key file.
+ * @param scopes The scopes to request.
+ * @returns A `[scheme, credential]` pair.
+ */
+export declare function serviceAccountDictToSchemeCredential(config: Record<string, unknown>, scopes: string[]): [AuthScheme, AuthCredential];
+/**
+ * Creates a bearer scheme and a service-account credential from an already
+ * built `ServiceAccount`.
+ *
+ * @param config The service-account configuration.
+ * @returns A `[scheme, credential]` pair.
+ */
+export declare function serviceAccountSchemeCredential(config: ServiceAccount): [AuthScheme, AuthCredential];
+/**
+ * Builds an OpenID Connect scheme and credential from a configuration object
+ * and a client-secret object.
+ *
+ * @param configDict An OpenID Connect configuration. Snake_case keys, as a
+ *   discovery document delivers them, are accepted and normalized.
+ * @param scopes The scopes to request.
+ * @param credentialDict The Google OAuth client secret. Its keys stay
+ *   snake_case, because it is an on-disk wire format. A `{web: {…}}` or
+ *   `{installed: {…}}` wrapper is unwrapped.
+ * @returns A `[scheme, credential]` pair.
+ * @throws Error When the configuration or the client secret is incomplete.
+ */
+export declare function openidDictToSchemeCredential(configDict: Record<string, unknown>, scopes: string[], credentialDict: Record<string, unknown>): [OpenIdConnectWithConfig, AuthCredential];
+/**
+ * Fetches an OpenID Connect discovery document and pairs it with a client
+ * secret.
+ *
+ * The URL is used as given. A caller that accepts it from an untrusted source
+ * has to validate it first, because this function performs the request.
+ *
+ * @param openidUrl The OpenID Connect discovery URL.
+ * @param scopes The scopes to request.
+ * @param credentialDict The Google OAuth client secret, keyed snake_case.
+ * @returns A `[scheme, credential]` pair.
+ * @throws Error When the request fails, the body is not a JSON object, or the
+ *   configuration is incomplete.
+ */
+export declare function openidUrlToSchemeCredential(openidUrl: string, scopes: string[], credentialDict: Record<string, unknown>): Promise<[OpenIdConnectWithConfig, AuthCredential]>;
+/**
+ * Converts a scheme and credential into the tool parameter that carries the
+ * credential, plus the value to send for it.
+ *
+ * Service-account, OAuth2, and OpenID Connect credentials reach this function
+ * already exchanged for a bearer token, so they take the HTTP branch.
+ *
+ * @param authScheme The auth scheme.
+ * @param authCredential The auth credential.
+ * @returns A `[parameter, values]` pair, both `undefined` when the credential
+ *   carries nothing to send.
+ * @throws Error For basic authentication, which is not supported, and for a
+ *   scheme and credential combination that cannot be expressed as a parameter.
+ */
+export declare function credentialToParam(authScheme: AuthScheme, authCredential?: AuthCredential): [ApiParameter | undefined, Record<string, string> | undefined];
+/**
+ * Converts a security scheme object out of an OpenAPI document into an
+ * `AuthScheme`.
+ *
+ * @example
+ * const scheme = dictToAuthScheme({
+ *   type: 'apiKey',
+ *   in: 'header',
+ *   name: 'X-API-Key',
+ * });
+ *
+ * @param data The security scheme object.
+ * @returns The validated auth scheme.
+ * @throws Error When `type` is missing or unrecognised, or the rest of the
+ *   object does not match the shape that type requires.
+ */
+export declare function dictToAuthScheme(data: Record<string, unknown>): AuthScheme;

package/dist/types/tools/openapi_tool/auth/credential_exchangers/auto_auth_credential_exchanger.d.ts

@@ -3,18 +3,47 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthCredential, AuthCredentialTypes } from '../../../../auth/auth_credential.js';
 import { AuthScheme } from '../../../../auth/auth_schemes.js';
 import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
+/**
+ * A map from auth credential type to the exchanger that handles it, merged
+ * over the built-in defaults.
+ */
+export type CustomCredentialExchangers = Partial<Record<AuthCredentialTypes, BaseCredentialExchanger>>;
 /**
  * Automatically selects the appropriate credential exchanger based on the auth scheme.
  * Ported from Python implementation.
+ *
+ * @example
+ * // Common case: a built-in exchanger handles the credential.
+ * const exchanger = new AutoAuthCredentialExchanger();
+ * const result = await exchanger.exchange({
+ *   authScheme: serviceAccountScheme,
+ *   authCredential: serviceAccountCredential,
+ * });
+ * // result.credential carries an OAuth token as a bearer token.
+ *
+ * @example
+ * // Use CustomAuthExchanger for OAuth2 instead of the built-in exchanger.
+ * const exchanger = new AutoAuthCredentialExchanger({
+ *   [AuthCredentialTypes.OAUTH2]: new CustomAuthExchanger(),
+ * });
  */
 export declare class AutoAuthCredentialExchanger implements BaseCredentialExchanger {
     private exchangers;
-    constructor();
+    /**
+     * @param customExchangers - Optional exchangers that add to or override the
+     *   built-in ones. The key is the auth credential type; the value is the
+     *   exchanger instance to use for that type.
+     */
+    constructor(customExchangers?: CustomCredentialExchangers);
     exchange(params: {
         authScheme?: AuthScheme;
         authCredential: AuthCredential;
     }): Promise<ExchangeResult>;
+    exchange(params: {
+        authScheme?: AuthScheme;
+        authCredential?: AuthCredential;
+    }): Promise<ExchangeResult | null>;
 }

package/dist/types/tools/openapi_tool/auth/credential_exchangers/base_auth_credential_exchanger.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../../auth/auth_schemes.js';
+/**
+ * Error raised when a required authentication credential is missing.
+ */
+export declare class AuthCredentialMissingError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base class for authentication credential exchangers.
+ *
+ * A subclass exchanges the credential an OpenAPI tool was configured with for
+ * one that can be sent to the API. The base implementation always throws, so a
+ * subclass that forgets to override the method fails on the first call rather
+ * than silently returning nothing.
+ */
+export declare class BaseAuthCredentialExchanger {
+    /**
+     * Exchanges the provided authentication credential for a usable
+     * token or credential.
+     *
+     * @param _authScheme The security scheme.
+     * @param _authCredential The authentication credential.
+     * @returns An updated AuthCredential object containing the fetched
+     *     credential. For simple schemes like API key, it may return the original
+     *     credential if no exchange is needed.
+     * @throws {Error} If the method is not implemented by a subclass.
+     */
+    exchangeCredential(_authScheme: AuthScheme, _authCredential?: AuthCredential): AuthCredential;
+}

package/dist/types/tools/openapi_tool/auth/credential_exchangers/oauth2_exchanger.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../../auth/auth_schemes.js';
+import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
+/**
+ * Validates that the scheme and the credential can produce a bearer token.
+ *
+ * @param authScheme - The OpenID Connect or OAuth2 auth scheme.
+ * @param authCredential - The auth credential to validate.
+ * @throws Error - If the credential is absent, the scheme is
+ *     not OpenID Connect or OAuth2, or the credential carries neither `oauth2`
+ *     nor `http`.
+ */
+export declare function checkSchemeCredentialType(authScheme: AuthScheme, authCredential?: AuthCredential): asserts authCredential is AuthCredential;
+/**
+ * Converts an OAuth2 access token into an HTTP bearer credential.
+ *
+ * @param authCredential - The auth credential holding the access token.
+ * @returns A new credential holding the access token as an HTTP bearer token,
+ *     or the original credential when there is no access token to convert. The
+ *     input credential is never modified.
+ */
+export declare function generateAuthToken(authCredential: AuthCredential): AuthCredential;
+/**
+ * Exchanges an OAuth2 or OpenID Connect credential for an HTTP bearer one.
+ *
+ * @param authScheme - The auth scheme.
+ * @param authCredential - The auth credential.
+ * @returns The credential unchanged when it already carries `http`, a new HTTP
+ *     bearer credential when it carries an access token, or `null` when there
+ *     is no token to convert.
+ * @throws Error - If the scheme or the credential is invalid.
+ */
+export declare function exchangeCredential(authScheme: AuthScheme, authCredential?: AuthCredential): AuthCredential | null;
+/**
+ * Converts OAuth2 and OpenID Connect credentials into HTTP bearer credentials.
+ *
+ * Ports `OAuth2CredentialExchanger` from adk-python
+ * `src/google/adk/tools/openapi_tool/auth/credential_exchangers/oauth2_exchanger.py`
+ * at tag `v0.1.0`. The adk-js class carries a different name because
+ * `OAuth2CredentialExchanger` in `core/src/auth/oauth2/` already owns that one,
+ * and it solves a different problem: it fetches tokens from the token endpoint,
+ * where this class converts a token it is given.
+ */
+export declare class OAuth2BearerExchanger implements BaseCredentialExchanger {
+    exchange(params: {
+        authScheme?: AuthScheme;
+        authCredential: AuthCredential;
+    }): Promise<ExchangeResult>;
+}

package/dist/types/tools/openapi_tool/auth/credential_exchangers/service_account_exchanger.d.ts

@@ -8,7 +8,6 @@ import { AuthScheme } from '../../../../auth/auth_schemes.js';
 import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
 /**
  * Fetches credentials for Google Service Account.
- * Ported from Python implementation.
  */
 export declare class ServiceAccountCredentialExchanger implements BaseCredentialExchanger {
     exchange(params: {

package/dist/types/tools/openapi_tool/common/common.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { OpenAPIV3 } from 'openapi-types';
+import { ApiParameter } from '../openapi_spec_parser/operation_parser.js';
+/**
+ * The type hints these helpers emit are Python tokens, in a TypeScript SDK,
+ * on purpose. They are assembled into a tool description that reaches the
+ * model, so the same OpenAPI operation has to describe itself identically in
+ * adk-js and in adk-python. The reference is adk-python
+ * `src/google/adk/tools/openapi_tool/common/common.py`.
+ */
+/** Input to {@link createApiParameter}; `name` is derived when omitted. */
+export interface ApiParameterInit {
+    originalName: string;
+    paramLocation: string;
+    paramSchema: OpenAPIV3.SchemaObject;
+    description?: string;
+    name?: string;
+    required?: boolean;
+}
+/**
+ * Returns the Python type hint for an OpenAPI schema.
+ *
+ * @param schema The schema to describe, if any.
+ * @returns A Python type name such as `str`, `List[int]` or `Dict[str, Any]`.
+ *     A missing or unrecognised type gives `Any`.
+ */
+export declare function getTypeHint(schema: OpenAPIV3.SchemaObject | undefined): string;
+/**
+ * Generates the docstring line documenting one parameter.
+ *
+ * @param param The parameter to document.
+ * @returns A line of the form `name (type): description`, followed by an
+ *     indented property list when the schema is an object with properties.
+ */
+export declare function generateParamDoc(param: ApiParameter): string;
+/**
+ * Generates the docstring block documenting the return value.
+ *
+ * Uses the 2xx response with the smallest status code that has content.
+ *
+ * @param responses The responses of an OpenAPI operation.
+ * @returns A line of the form `Returns (type): description`, or `''` when no
+ *     2xx response has content.
+ */
+export declare function generateReturnDoc(responses: OpenAPIV3.ResponsesObject): string;
+/**
+ * Builds an {@link ApiParameter}, deriving the fields adk-python derives in
+ * `ApiParameter.model_post_init`.
+ *
+ * `name` falls back to the reserved-word-safe snake_case form of
+ * `originalName`, and `description` falls back to the schema description.
+ *
+ * @param init The parameter fields.
+ * @returns The parameter with its derived fields filled in.
+ */
+export declare function createApiParameter(init: ApiParameterInit): ApiParameter;

package/dist/types/tools/openapi_tool/openapi_spec_parser/openapi_spec_parser.d.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { OpenAPIV3 } from 'openapi-types';
+import { AuthCredential } from '../../../auth/auth_credential.js';
 import { ApiParameter } from './operation_parser.js';
 export interface OperationEndpoint {
     baseUrl: string;
@@ -18,6 +19,12 @@ export interface ParsedOperation {
     parameters: ApiParameter[];
     returnValue?: ApiParameter;
     authScheme?: OpenAPIV3.SecuritySchemeObject;
+    /**
+     * Credential for the operation. The parser leaves this undefined; a caller
+     * that builds a `ParsedOperation` by hand can set it, and `OpenAPIToolset`
+     * passes it to the tool it creates.
+     */
+    authCredential?: AuthCredential;
 }
 export declare class OpenApiSpecParser {
     private preservePropertyNames;

package/dist/types/tools/openapi_tool/openapi_spec_parser/operation_parser.d.ts

@@ -19,13 +19,32 @@ export interface ApiParameter {
  * that are compatible with Gemini's tool function declarations.
  */
 export declare class OperationParser {
-    private readonly operation;
     private params;
     private returnValue?;
     private preservePropertyNames;
-    constructor(operation: OpenAPIV3.OperationObject, options?: {
+    private readonly operation;
+    /**
+     * @param operation The operation to parse. A string is parsed as JSON, and a
+     *     plain object is used as given.
+     * @param options.preservePropertyNames Keeps the original parameter and
+     *     function names instead of converting them to snake_case.
+     * @param options.shouldParse Whether to parse the operation during
+     *     construction. Defaults to `true`.
+     */
+    constructor(operation: OpenAPIV3.OperationObject | Record<string, unknown> | string, options?: {
         preservePropertyNames?: boolean;
+        shouldParse?: boolean;
     });
+    /**
+     * Builds a parser from parameters that were already parsed, without walking
+     * the operation again.
+     *
+     * @param operation The operation the parameters came from.
+     * @param params The parsed parameters.
+     * @param returnValue The parsed return value, if any.
+     * @returns A parser holding the given parameters.
+     */
+    static load(operation: OpenAPIV3.OperationObject | Record<string, unknown> | string, params: ApiParameter[], returnValue?: ApiParameter): OperationParser;
     private getParamName;
     private processOperationParameters;
     private processRequestBody;
@@ -56,4 +75,39 @@ export declare class OperationParser {
      * @returns A string representing the description.
      */
     getDescription(): string;
+    /**
+     * Gets the name of the security scheme this operation declares.
+     *
+     * Only operation-level security is considered. Document-level security is
+     * not visible from here, so a caller that needs the fallback uses
+     * `OpenApiSpecParser` instead.
+     *
+     * @returns The first declared scheme name, or `''` when the operation
+     *     declares none.
+     */
+    getAuthSchemeName(): string;
+    /**
+     * Gets the parsed return value of the operation.
+     *
+     * @returns The return value, or `undefined` when the parser was constructed
+     *     with `shouldParse: false` and nothing was loaded.
+     */
+    getReturnValue(): ApiParameter | undefined;
+    /**
+     * Gets the Python-style type hint of the return value.
+     *
+     * @returns A type name such as `str`, or `Any` when the operation declares
+     *     no typed 2xx response.
+     */
+    getReturnTypeHint(): string;
+    /**
+     * Generates a Python-style docstring describing the operation, every
+     * parameter and the return value.
+     *
+     * The type names inside it are Python's, because the artifact is a docstring
+     * in adk-python's format and the same text reaches the model in both SDKs.
+     *
+     * @returns The generated docstring.
+     */
+    getPydocString(): string;
 }