@google/adk 0.1.0

package/dist/types/auth/auth_credential.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Represents the secret token value for HTTP authentication, like user name,
+ * password, oauth token, etc.
+ */
+export interface HttpCredentials {
+    username?: string;
+    password?: string;
+    token?: string;
+}
+/**
+ * The credentials and metadata for HTTP authentication.
+ */
+export interface HttpAuth {
+    /**
+     * The name of the HTTP Authorization scheme to be used in the Authorization
+     * header as defined in RFC7235. The values used SHOULD be registered in the
+     * IANA Authentication Scheme registry.
+     * Examples: 'basic', 'bearer'
+     */
+    scheme: string;
+    credentials: HttpCredentials;
+}
+/**
+ * Represents credential value and its metadata for a OAuth2 credential.
+ */
+export interface OAuth2Auth {
+    clientId?: string;
+    clientSecret?: string;
+    /**
+     * tool or adk can generate the authUri with the state info thus client can
+     * verify the state
+     */
+    authUri?: string;
+    state?: string;
+    /**
+     * tool or adk can decide the redirect_uri if they don't want client to decide
+     */
+    redirectUri?: string;
+    authResponseUri?: string;
+    authCode?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    expiresIn?: number;
+}
+/**
+ * Represents Google Service Account configuration.
+ * @example
+ * config = {
+ *   type: "service_account",
+ *   projectId: "your_project_id",
+ *   privateKeyId: "your_private_key_id",
+ *   privateKey: "-----BEGIN PRIVATE KEY-----...",
+ *   clientEmail: "...@....iam.gserviceaccount.com",
+ *   clientId: "your_client_id",
+ *   authUri: "https://accounts.google.com/o/oauth2/auth",
+ *   tokenUri: "https://oauth2.googleapis.com/token",
+ *   authProviderX509CertUrl: "https://www.googleapis.com/oauth2/v1/certs",
+ *   clientX509CertUrl: "https://www.googleapis.com/robot/v1/metadata/x509/...",
+ *   universeDomain: "googleapis.com",
+ * }
+ */
+export interface ServiceAccountCredential {
+    /**
+     * The type should be 'service_account'.
+     */
+    type: 'service_account';
+    /**
+     * The project ID of the Google Cloud project.
+     */
+    projectId: string;
+    /**
+     * The ID of the private key.
+     */
+    privateKeyId: string;
+    /**
+     * The private key value.
+     */
+    privateKey: string;
+    /**
+     * The client email.
+     */
+    clientEmail: string;
+    /**
+     * The client ID.
+     */
+    clientId: string;
+    /**
+     * The authorization URI.
+     */
+    authUri: string;
+    /**
+     * The token URI.
+     */
+    tokenUri: string;
+    /**
+     * URL for auth provider's X.509 cert.
+     */
+    authProviderX509CertUrl: string;
+    /**
+     * URL for the client's X.509 cert.
+     */
+    clientX509CertUrl: string;
+    /**
+     * The universe domain.
+     */
+    universeDomain: string;
+}
+/**
+ * Represents Google Service Account configuration.
+ */
+export interface ServiceAccount {
+    serviceAccountCredential?: ServiceAccountCredential;
+    scopes?: string[];
+    useDefaultCredential?: boolean;
+}
+export declare enum AuthCredentialTypes {
+    /**
+     * API Key credential:
+     * @see {@link https://swagger.io/docs/specification/v3_0/authentication/api-keys/}
+     */
+    API_KEY = "apiKey",
+    /**
+     * Credentials for HTTP Auth schemes:
+     * @see {@link https://www.iana.org/assignments/http-authschemes/http-auth-schemes.xhtml}
+     */
+    HTTP = "http",
+    /**
+     * OAuth2 credentials:
+     * @see {@link https://swagger.io/docs/specification/v3_0/authentication/oauth2/}
+     */
+    OAUTH2 = "oauth2",
+    /**
+     * Open ID Connect credentials:
+     * @see {@link https://swagger.io/docs/specification/v3_0/authentication/openid-connect-discovery/}
+     */
+    OPEN_ID_CONNECT = "openIdConnect",
+    /**
+     * Service Account credentials:
+     * @see {@link https://cloud.google.com/iam/docs/service-account-creds}
+     */
+    SERVICE_ACCOUNT = "serviceAccount"
+}
+/**
+ * Data class representing an authentication credential.
+ *
+ * To exchange for the actual credential, please use
+ * CredentialExchanger.exchangeCredential().
+ *
+ * @example
+ * // API Key Auth
+ * const authCredential: AuthCredential = {
+ *   authType: AuthCredentialTypes.API_KEY,
+ *   apiKey: "your_api_key",
+ * };
+ *
+ * @example
+ * // HTTP Auth
+ * const authCredential: AuthCredential = {
+ *   authType: AuthCredentialTypes.HTTP,
+ *   http: {
+ *     scheme: "basic",
+ *     credentials: {
+ *       username: "user",
+ *       password: "password",
+ *     },
+ *   }
+ * }
+ *
+ * @example
+ * // OAuth2 Bearer Token in HTTP Header
+ * const authCredential: AuthCredential = {
+ *   authType: AuthCredentialTypes.HTTP,
+ *   http: {
+ *     scheme: "bearer",
+ *     credentials: {
+ *       token: "your_access_token",
+ *     },
+ *   }
+ * }
+ *
+ * @example
+ * // OAuth2 Auth with Authorization Code Flow
+ * const authCredential: AuthCredential = {
+ *   authType: AuthCredentialTypes.OAUTH2,
+ *   oauth2: {
+ *     clientId: "your_client_id",
+ *     clientSecret: "your_client_secret",
+ *   }
+ * }
+ *
+ * @example:
+ * // Open ID Connect Auth
+ * const authCredential: AuthCredential = {
+ *   authType: AuthCredentialTypes.OPEN_ID_CONNECT,
+ *   oauth2: {
+ *     clientId: "1234",
+ *     clientSecret: "secret",
+ *     redirectUri: "https://example.com",
+ *     scopes: ["scope1", "scope2"],
+ *   }
+ * }
+ *
+ * @example:
+ * // Auth with resource reference
+ * const authCredential: AuthCredential = {
+ *   authType: AuthCredentialTypes.API_KEY,
+ *   resourceRef: "projects/1234/locations/us-central1/resources/resource1"
+ * }
+ */
+export interface AuthCredential {
+    authType: AuthCredentialTypes;
+    /**
+     * Resource reference for the credential.
+     * This will be supported in the future.
+     */
+    resourceRef?: string;
+    apiKey?: string;
+    http?: HttpAuth;
+    serviceAccount?: ServiceAccount;
+    oauth2?: OAuth2Auth;
+}

package/dist/types/auth/auth_handler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { State } from '../sessions/state.js';
+import { AuthCredential } from './auth_credential.js';
+import { AuthConfig } from './auth_tool.js';
+/**
+ * A handler that handles the auth flow in Agent Development Kit to help
+ * orchestrates the credential request and response flow (e.g. OAuth flow)
+ * This class should only be used by Agent Development Kit.
+ */
+export declare class AuthHandler {
+    private readonly authConfig;
+    constructor(authConfig: AuthConfig);
+    getAuthResponse(state: State): AuthCredential | undefined;
+    generateAuthRequest(): AuthConfig;
+    /**
+     * Generates an response containing the auth uri for user to sign in.
+     *
+     * @return An AuthCredential object containing the auth URI and state.
+     * @throws Error: If the authorization endpoint is not configured in the
+     *     auth scheme.
+     */
+    generateAuthUri(): AuthCredential | undefined;
+}

package/dist/types/auth/auth_schemes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { OpenAPIV3 } from 'openapi-types';
+type Oauth2Flow = OpenAPIV3.OAuth2SecurityScheme['flows'];
+export interface OpenIdConnectWithConfig extends OpenAPIV3
+    .OpenIdSecurityScheme {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    userinfoEndpoint?: string;
+    revocationEndpoint?: string;
+    tokenEndpointAuthMethodsSupported?: string[];
+    grantTypesSupported?: string[];
+    scopes?: string[];
+}
+/**
+ * AuthSchemes contains SecuritySchemes from OpenAPI 3.0 and an extra flattened
+ * OpenIdConnectWithConfig.
+ */
+export type AuthScheme = OpenAPIV3.SecuritySchemeObject | OpenIdConnectWithConfig;
+/**
+ * Represents the OAuth2 flow (or grant type).
+ */
+export declare enum OAuthGrantType {
+    CLIENT_CREDENTIALS = "client_credentials",
+    AUTHORIZATION_CODE = "authorization_code",
+    IMPLICIT = "implicit",
+    PASSWORD = "password"
+}
+/**
+ * Converts an OAuthFlows object to a OAuthGrantType.
+ */
+export declare function getOAuthGrantTypeFromFlow(flow: Oauth2Flow): OAuthGrantType | undefined;
+export {};

package/dist/types/auth/auth_tool.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from './auth_credential.js';
+import { AuthScheme } from './auth_schemes.js';
+/**
+ * The auth config sent by tool asking client to collect auth credentials and
+ * adk and client will help to fill in the response.
+ */
+export interface AuthConfig {
+    /**
+     * The auth scheme used to collect credentials
+     */
+    authScheme: AuthScheme;
+    /**
+     * The raw auth credential used to collect credentials. The raw auth
+     * credentials are used in some auth scheme that needs to exchange auth
+     * credentials. e.g. OAuth2 and OIDC. For other auth scheme, it could be
+     * undefined.
+     */
+    rawAuthCredential?: AuthCredential;
+    /**
+     * The exchanged auth credential used to collect credentials. adk and client
+     * will work together to fill it. For those auth scheme that doesn't need to
+     * exchange auth credentials, e.g. API key, service account etc. It's filled
+     * by client directly. For those auth scheme that need to exchange auth
+     * credentials, e.g. OAuth2 and OIDC, it's first filled by adk. If the raw
+     * credentials passed by tool only has client id and client credential, adk
+     * will help to generate the corresponding authorization uri and state and
+     * store the processed credential in this field. If the raw credentials passed
+     * by tool already has authorization uri, state, etc. then it's copied to this
+     * field. Client will use this field to guide the user through the OAuth2 flow
+     * and fill auth response in this field
+     */
+    exchangedAuthCredential?: AuthCredential;
+    /**
+     * A user specified key used to load and save this credential in a credential
+     * service.
+     */
+    credentialKey: string;
+}
+/**
+ * The arguments for the special long running function tool that is used to
+ * request end user credentials.
+ */
+export interface AuthToolArguments {
+    functionCallId: string;
+    authConfig: AuthConfig;
+}

package/dist/types/auth/credential_service/base_credential_service.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ToolContext } from '../../tools/tool_context.js';
+import { AuthCredential } from '../auth_credential.js';
+import { AuthConfig } from '../auth_tool.js';
+/**
+ * Abstract class for Service that loads / saves tool credentials from / to the
+ * backend credential store.
+ */
+export interface BaseCredentialService {
+    /**
+     * Loads the credential by auth config and current tool context from the
+     *  backend credential store.
+     *
+     * @param authConfig The auth config which contains the auth scheme and auth
+     *     credential information. auth_config.get_credential_key will be used to
+     *     build the key to load the credential.
+     * @param toolContext The context of the current invocation when the tool is
+     *     trying to load the credential.
+     * @return A promise that resolves to the credential saved in the store.
+     */
+    loadCredential(authConfig: AuthConfig, toolContext: ToolContext): Promise<AuthCredential | undefined>;
+    saveCredential(authConfig: AuthConfig, toolContext: ToolContext): Promise<void>;
+}

package/dist/types/auth/credential_service/in_memory_credential_service.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ToolContext } from '../../tools/tool_context.js';
+import { AuthCredential } from '../auth_credential.js';
+import { AuthConfig } from '../auth_tool.js';
+import { BaseCredentialService } from './base_credential_service.js';
+/**
+ * @experimental  (Experimental, subject to change) Class for in memory
+ * implementation of credential service
+ */
+export declare class InMemoryCredentialService implements BaseCredentialService {
+    private readonly credentials;
+    loadCredential(authConfig: AuthConfig, toolContext: ToolContext): Promise<AuthCredential | undefined>;
+    saveCredential(authConfig: AuthConfig, toolContext: ToolContext): Promise<void>;
+    private getBucketForCurrentContext;
+}

package/dist/types/code_executors/base_code_executor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { InvocationContext } from '../agents/invocation_context.js';
+import { CodeExecutionInput, CodeExecutionResult } from './code_execution_utils.js';
+/**
+ * The parameters for executing code.
+ * */
+export interface ExecuteCodeParams {
+    /** The invocation context of the code execution. */
+    invocationContext: InvocationContext;
+    /** The input of the code execution. */
+    codeExecutionInput: CodeExecutionInput;
+}
+/**
+ * The code executor allows the agent to execute code blocks from model
+ * responses and incorporate the execution results into the final response.
+ */
+export declare abstract class BaseCodeExecutor {
+    /**
+     * If true, extract and process data files from the model request
+     * and attach them to the code executor.
+     *
+     * Supported data file MimeTypes are [text/csv].
+     * Default to false.
+     */
+    optimizeDataFile: boolean;
+    /**
+     * Whether the code executor is stateful. Default to false.
+     */
+    stateful: boolean;
+    /**
+     * The number of attempts to retry on consecutive code execution errors.
+     * Default to 2.
+     */
+    errorRetryAttempts: number;
+    /**
+     * The list of the enclosing delimiters to identify the code blocks.
+     * For example, the delimiter('```python\\n', '\\n```') can be  used to
+     * identify code blocks with the following format::
+     *
+     * ```python
+     *  print("hello")
+     * ```
+     */
+    codeBlockDelimiters: Array<[string, string]>;
+    /**
+     * The delimiters to format the code execution result.
+     */
+    executionResultDelimiters: [string, string];
+    /**
+     * Executes code and return the code execution result.
+     *
+     * @param params The parameters for executing code.
+     * @return The result of the code execution.
+     */
+    abstract executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
+}

package/dist/types/code_executors/built_in_code_executor.d.ts

@@ -0,0 +1,13 @@
+import { LlmRequest } from '../models/llm_request.js';
+import { BaseCodeExecutor, ExecuteCodeParams } from './base_code_executor.js';
+import { CodeExecutionResult } from './code_execution_utils.js';
+/**
+ * A code executor that uses the Model's built-in code executor.
+ *
+ * Currently only supports Gemini 2.0+ models, but will be expanded to
+ * other models.
+ */
+export declare class BuiltInCodeExecutor extends BaseCodeExecutor {
+    executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
+    processLlmRequest(llmRequest: LlmRequest): void;
+}

package/dist/types/code_executors/code_execution_utils.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content, Part } from '@google/genai';
+/**
+ * A structure that contains a file name and its content
+ */
+export interface File {
+    /**
+     * The name of the file with file extension(e.g., ' file.csv')
+     * */
+    name: string;
+    /**
+     * The base64 - encoded bytes of the file content.
+     * */
+    content: string;
+    /**
+     * The mime type of the file (e.g., ' image / png')
+     * */
+    mimeType: string;
+}
+/**
+ * A structure that contains the input of code execution.
+ * */
+export interface CodeExecutionInput {
+    /**
+     * The code to execute.
+     * */
+    code: string;
+    /**
+     * The input files available to the code.
+     * */
+    inputFiles: File[];
+    /**
+     * The execution ID for the stateful code execution.
+     * */
+    executionId?: string;
+}
+/**
+ * A structure that contains the result of code execution.
+ * */
+export interface CodeExecutionResult {
+    /**
+     * The standard output of the code execution.
+     * */
+    stdout: string;
+    /**
+     * The standard error of the code execution.
+     * */
+    stderr: string;
+    /**
+     * The output files from the code execution.
+     * */
+    outputFiles: File[];
+}
+/**
+ * Gets the file content as a base64-encoded bytes.
+ *
+ * @param data The file content bytes.
+ * @return The file content as a base64-encoded bytes.
+ */
+export declare function getEncodedFileContent(data: string): string;
+/**
+ * Extracts the first code block from the content and truncate everything after
+ * it.
+ *
+ * @param content The mutable content to extract the code from.
+ * @param codeBlockDelimiters The list of the enclosing delimiters to identify
+ *     the code blocks.
+ * @return The first code block if found, otherwise None.
+ */
+export declare function extractCodeAndTruncateContent(content: Content, codeBlockDelimiters: Array<[string, string]>): string;
+/**
+ * Builds an executable code part with code string.
+ *
+ * @param code The code string.
+ * @return The constructed executable code part.
+ */
+export declare function buildExecutableCodePart(code: string): Part;
+/**
+ * Builds the code execution result part from the code execution result.
+ *
+ * @param codeExecutionResult The code execution result.
+ * @return The code execution result part.
+ */
+export declare function buildCodeExecutionResultPart(codeExecutionResult: CodeExecutionResult): Part;
+/**
+ * Converts the code execution parts to text parts in a Content.
+ *
+ * @param content The mutable content to convert the code execution parts to
+ *     text parts.
+ * @param codeBlockDelimiter The delimiter to format the code block.
+ * @param executionResultDelimiters The delimiter to format the code execution
+ *     result.
+ * @return The converted content.
+ */
+export declare function convertCodeExecutionParts(content: Content, codeBlockDelimiter: [string, string], executionResultDelimiters: [string, string]): void;

package/dist/types/code_executors/code_executor_context.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { State } from '../sessions/state.js';
+import { File } from './code_execution_utils.js';
+/**
+ * The parameters for updating the code execution result.
+ * */
+export interface UpdateCodeExecutionResultParams {
+    invocationId: string;
+    code: string;
+    resultStdout: string;
+    resultStderr: string;
+}
+/**
+ * The persistent context used to configure the code executor.
+ */
+export declare class CodeExecutorContext {
+    private readonly sessionState;
+    private readonly context;
+    constructor(sessionState: State);
+    /**
+     * Gets the state delta to update in the persistent session state.
+     * @return The state delta to update in the persistent session state.
+     */
+    getStateDelta(): Record<string, unknown>;
+    /**
+     * Gets the execution ID for the code executor.
+     * @return The execution ID for the code executor.
+     */
+    getExecutionId(): string | undefined;
+    /**
+     * Sets the execution ID for the code executor.
+     * @param executionId The execution ID to set.
+     */
+    setExecutionId(executionId: string): void;
+    /**
+     * Gets the processed file names from the session state.
+     * @return A list of processed file names in the code executor context.
+     */
+    getProcessedFileNames(): string[];
+    /**
+     * Adds the processed file names to the session state.
+     * @param fileNames The file names to add to the session state.
+     */
+    addProcessedFileNames(fileNames: string[]): void;
+    /**
+     * Gets the input files from the session state.
+     * @return A list of input files in the code executor context.
+     */
+    getInputFiles(): File[];
+    /**
+     * Adds the input files to the session state.
+     * @param inputFiles The input files to add to the session state.
+     */
+    addInputFiles(inputFiles: File[]): void;
+    clearInputFiles(): void;
+    /**
+     * Gets the error count from the session state.
+     * @param invocationId The invocation ID to get the error count for.
+     * @return The error count for the given invocation ID.
+     */
+    getErrorCount(invocationId: string): number;
+    /**
+     * Increments the error count from the session state.
+     * @param invocationId The invocation ID to increment the error count for.
+     */
+    incrementErrorCount(invocationId: string): void;
+    /**
+     * Resets the error count from the session state.
+     * @param invocationId The invocation ID to reset the error count for.
+     */
+    resetErrorCount(invocationId: string): void;
+    /**
+     * Updates the code execution result.
+     * @param invocationId The invocation ID to update the code execution result
+     *     for.
+     * @param code The code to execute.
+     * @param resultStdout The standard output of the code execution.
+     * @param resultStderr The standard error of the code execution.
+     */
+    updateCodeExecutionResult({ invocationId, code, resultStdout, resultStderr, }: UpdateCodeExecutionResultParams): void;
+    /**
+     * Gets the code executor context from the session state.
+     * @param invocationId The session state to get the code executor context
+     *     from.
+     * @return The code execution context for the given invocation ID.
+     */
+    getCodeExecutionContext(invocationId: string): Record<string, unknown>;
+}