@google/adk 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/dist/cjs/agents/base_agent.js +52 -24
  2. package/dist/cjs/agents/callback_context.js +4 -1
  3. package/dist/cjs/agents/content_processor_utils.js +15 -7
  4. package/dist/cjs/agents/functions.js +79 -29
  5. package/dist/cjs/agents/invocation_context.js +3 -1
  6. package/dist/cjs/agents/llm_agent.js +188 -108
  7. package/dist/cjs/agents/loop_agent.js +18 -6
  8. package/dist/cjs/agents/parallel_agent.js +20 -7
  9. package/dist/cjs/agents/readonly_context.js +4 -1
  10. package/dist/cjs/agents/sequential_agent.js +34 -12
  11. package/dist/cjs/artifacts/gcs_artifact_service.js +28 -20
  12. package/dist/cjs/artifacts/in_memory_artifact_service.js +18 -4
  13. package/dist/cjs/auth/auth_handler.js +3 -1
  14. package/dist/cjs/code_executors/base_code_executor.js +14 -2
  15. package/dist/cjs/code_executors/built_in_code_executor.js +21 -5
  16. package/dist/cjs/code_executors/code_executor_context.js +5 -5
  17. package/dist/cjs/common.js +45 -0
  18. package/dist/cjs/events/event.js +1 -3
  19. package/dist/cjs/examples/base_example_provider.js +18 -2
  20. package/dist/cjs/examples/example_util.js +1 -1
  21. package/dist/cjs/index.js +19 -19
  22. package/dist/cjs/index.js.map +4 -4
  23. package/dist/cjs/memory/in_memory_memory_service.js +3 -1
  24. package/dist/cjs/models/base_llm.js +8 -4
  25. package/dist/cjs/models/gemini_llm_connection.js +1 -0
  26. package/dist/cjs/models/google_llm.js +3 -3
  27. package/dist/cjs/plugins/base_plugin.js +71 -49
  28. package/dist/cjs/plugins/logging_plugin.js +50 -13
  29. package/dist/cjs/plugins/plugin_manager.js +56 -24
  30. package/dist/cjs/plugins/security_plugin.js +5 -2
  31. package/dist/cjs/runner/runner.js +126 -101
  32. package/dist/cjs/sessions/in_memory_session_service.js +38 -14
  33. package/dist/cjs/telemetry/google_cloud.js +7 -9
  34. package/dist/cjs/telemetry/setup.js +15 -7
  35. package/dist/cjs/telemetry/tracing.js +37 -15
  36. package/dist/cjs/tools/agent_tool.js +26 -13
  37. package/dist/cjs/tools/base_tool.js +19 -7
  38. package/dist/cjs/tools/forwarding_artifact_service.js +1 -1
  39. package/dist/cjs/tools/function_tool.js +15 -7
  40. package/dist/cjs/tools/google_search_tool.js +8 -4
  41. package/dist/cjs/tools/mcp/mcp_session_manager.js +16 -10
  42. package/dist/cjs/tools/mcp/mcp_tool.js +1 -3
  43. package/dist/cjs/tools/mcp/mcp_toolset.js +1 -1
  44. package/dist/cjs/tools/tool_context.js +4 -9
  45. package/dist/cjs/utils/env_aware_utils.js +1 -1
  46. package/dist/cjs/utils/gemini_schema_util.js +10 -4
  47. package/dist/cjs/utils/logger.js +47 -3
  48. package/dist/cjs/utils/simple_zod_to_json.js +100 -141
  49. package/dist/cjs/utils/variant_utils.js +1 -1
  50. package/dist/cjs/version.js +1 -1
  51. package/dist/esm/agents/base_agent.js +57 -25
  52. package/dist/esm/agents/callback_context.js +4 -1
  53. package/dist/esm/agents/content_processor_utils.js +25 -9
  54. package/dist/esm/agents/functions.js +83 -29
  55. package/dist/esm/agents/invocation_context.js +3 -1
  56. package/dist/esm/agents/llm_agent.js +228 -116
  57. package/dist/esm/agents/loop_agent.js +16 -5
  58. package/dist/esm/agents/parallel_agent.js +18 -6
  59. package/dist/esm/agents/readonly_context.js +4 -1
  60. package/dist/esm/agents/sequential_agent.js +33 -12
  61. package/dist/esm/artifacts/gcs_artifact_service.js +28 -20
  62. package/dist/esm/artifacts/in_memory_artifact_service.js +18 -4
  63. package/dist/esm/auth/auth_handler.js +3 -1
  64. package/dist/esm/code_executors/base_code_executor.js +12 -1
  65. package/dist/esm/code_executors/built_in_code_executor.js +19 -4
  66. package/dist/esm/code_executors/code_executor_context.js +5 -5
  67. package/dist/esm/common.js +56 -11
  68. package/dist/esm/events/event.js +1 -3
  69. package/dist/esm/examples/base_example_provider.js +16 -1
  70. package/dist/esm/examples/example_util.js +4 -2
  71. package/dist/esm/index.js +19 -19
  72. package/dist/esm/index.js.map +4 -4
  73. package/dist/esm/memory/in_memory_memory_service.js +3 -1
  74. package/dist/esm/models/base_llm.js +8 -4
  75. package/dist/esm/models/gemini_llm_connection.js +1 -0
  76. package/dist/esm/models/google_llm.js +8 -4
  77. package/dist/esm/plugins/base_plugin.js +71 -49
  78. package/dist/esm/plugins/logging_plugin.js +55 -14
  79. package/dist/esm/plugins/plugin_manager.js +56 -24
  80. package/dist/esm/plugins/security_plugin.js +5 -2
  81. package/dist/esm/runner/runner.js +139 -105
  82. package/dist/esm/sessions/in_memory_session_service.js +41 -15
  83. package/dist/esm/telemetry/google_cloud.js +7 -9
  84. package/dist/esm/telemetry/setup.js +23 -9
  85. package/dist/esm/telemetry/tracing.js +37 -15
  86. package/dist/esm/tools/agent_tool.js +25 -13
  87. package/dist/esm/tools/base_tool.js +17 -6
  88. package/dist/esm/tools/forwarding_artifact_service.js +1 -1
  89. package/dist/esm/tools/function_tool.js +13 -8
  90. package/dist/esm/tools/google_search_tool.js +6 -3
  91. package/dist/esm/tools/long_running_tool.js +3 -1
  92. package/dist/esm/tools/mcp/mcp_session_manager.js +22 -12
  93. package/dist/esm/tools/mcp/mcp_tool.js +1 -3
  94. package/dist/esm/tools/mcp/mcp_toolset.js +1 -1
  95. package/dist/esm/tools/tool_context.js +4 -9
  96. package/dist/esm/utils/env_aware_utils.js +1 -1
  97. package/dist/esm/utils/gemini_schema_util.js +10 -4
  98. package/dist/esm/utils/logger.js +43 -2
  99. package/dist/esm/utils/simple_zod_to_json.js +102 -141
  100. package/dist/esm/utils/variant_utils.js +1 -1
  101. package/dist/esm/version.js +1 -1
  102. package/dist/types/agents/base_agent.d.ts +16 -4
  103. package/dist/types/agents/callback_context.d.ts +1 -1
  104. package/dist/types/agents/invocation_context.d.ts +4 -2
  105. package/dist/types/agents/llm_agent.d.ts +43 -31
  106. package/dist/types/agents/loop_agent.d.ts +17 -1
  107. package/dist/types/agents/parallel_agent.d.ts +17 -1
  108. package/dist/types/agents/sequential_agent.d.ts +17 -1
  109. package/dist/types/artifacts/in_memory_artifact_service.d.ts +3 -3
  110. package/dist/types/auth/auth_schemes.d.ts +5 -2
  111. package/dist/types/code_executors/base_code_executor.d.ts +14 -0
  112. package/dist/types/code_executors/built_in_code_executor.d.ts +20 -1
  113. package/dist/types/code_executors/code_executor_context.d.ts +2 -4
  114. package/dist/types/common.d.ts +40 -15
  115. package/dist/types/examples/base_example_provider.d.ts +16 -0
  116. package/dist/types/index.d.ts +3 -3
  117. package/dist/types/models/base_llm_connection.d.ts +1 -1
  118. package/dist/types/models/llm_response.d.ts +1 -1
  119. package/dist/types/plugins/base_plugin.d.ts +50 -40
  120. package/dist/types/plugins/logging_plugin.d.ts +12 -12
  121. package/dist/types/plugins/plugin_manager.d.ts +12 -12
  122. package/dist/types/plugins/security_plugin.d.ts +1 -1
  123. package/dist/types/runner/runner.d.ts +18 -10
  124. package/dist/types/sessions/in_memory_session_service.d.ts +5 -5
  125. package/dist/types/telemetry/setup.d.ts +1 -1
  126. package/dist/types/telemetry/tracing.d.ts +7 -6
  127. package/dist/types/tools/agent_tool.d.ts +15 -1
  128. package/dist/types/tools/base_tool.d.ts +15 -1
  129. package/dist/types/tools/base_toolset.d.ts +2 -1
  130. package/dist/types/tools/forwarding_artifact_service.d.ts +2 -2
  131. package/dist/types/tools/function_tool.d.ts +18 -4
  132. package/dist/types/tools/google_search_tool.d.ts +5 -6
  133. package/dist/types/tools/mcp/mcp_session_manager.d.ts +10 -3
  134. package/dist/types/tools/mcp/mcp_toolset.d.ts +1 -2
  135. package/dist/types/tools/tool_context.d.ts +1 -1
  136. package/dist/types/utils/gemini_schema_util.d.ts +4 -12
  137. package/dist/types/utils/logger.d.ts +11 -10
  138. package/dist/types/utils/simple_zod_to_json.d.ts +5 -4
  139. package/dist/types/version.d.ts +1 -1
  140. package/dist/web/agents/base_agent.js +103 -36
  141. package/dist/web/agents/callback_context.js +4 -1
  142. package/dist/web/agents/content_processor_utils.js +25 -9
  143. package/dist/web/agents/functions.js +83 -29
  144. package/dist/web/agents/invocation_context.js +3 -1
  145. package/dist/web/agents/llm_agent.js +282 -137
  146. package/dist/web/agents/loop_agent.js +16 -5
  147. package/dist/web/agents/parallel_agent.js +18 -6
  148. package/dist/web/agents/readonly_context.js +4 -1
  149. package/dist/web/agents/sequential_agent.js +33 -12
  150. package/dist/web/artifacts/gcs_artifact_service.js +25 -17
  151. package/dist/web/artifacts/in_memory_artifact_service.js +18 -4
  152. package/dist/web/auth/auth_handler.js +3 -1
  153. package/dist/web/code_executors/base_code_executor.js +12 -1
  154. package/dist/web/code_executors/built_in_code_executor.js +19 -4
  155. package/dist/web/code_executors/code_executor_context.js +5 -5
  156. package/dist/web/common.js +56 -11
  157. package/dist/web/events/event.js +1 -3
  158. package/dist/web/examples/base_example_provider.js +16 -1
  159. package/dist/web/examples/example_util.js +4 -2
  160. package/dist/web/index.js +1 -1
  161. package/dist/web/index.js.map +4 -4
  162. package/dist/web/memory/in_memory_memory_service.js +3 -1
  163. package/dist/web/models/base_llm.js +8 -4
  164. package/dist/web/models/gemini_llm_connection.js +1 -0
  165. package/dist/web/models/google_llm.js +8 -4
  166. package/dist/web/plugins/base_plugin.js +71 -49
  167. package/dist/web/plugins/logging_plugin.js +55 -14
  168. package/dist/web/plugins/plugin_manager.js +56 -24
  169. package/dist/web/plugins/security_plugin.js +5 -2
  170. package/dist/web/runner/runner.js +186 -119
  171. package/dist/web/sessions/in_memory_session_service.js +41 -15
  172. package/dist/web/telemetry/google_cloud.js +7 -9
  173. package/dist/web/telemetry/setup.js +23 -9
  174. package/dist/web/telemetry/tracing.js +37 -15
  175. package/dist/web/tools/agent_tool.js +25 -13
  176. package/dist/web/tools/base_tool.js +17 -6
  177. package/dist/web/tools/forwarding_artifact_service.js +1 -1
  178. package/dist/web/tools/function_tool.js +13 -8
  179. package/dist/web/tools/google_search_tool.js +6 -3
  180. package/dist/web/tools/long_running_tool.js +3 -1
  181. package/dist/web/tools/mcp/mcp_session_manager.js +22 -12
  182. package/dist/web/tools/mcp/mcp_tool.js +1 -3
  183. package/dist/web/tools/mcp/mcp_toolset.js +1 -1
  184. package/dist/web/tools/tool_context.js +4 -9
  185. package/dist/web/utils/env_aware_utils.js +1 -1
  186. package/dist/web/utils/gemini_schema_util.js +10 -4
  187. package/dist/web/utils/logger.js +43 -2
  188. package/dist/web/utils/simple_zod_to_json.js +102 -155
  189. package/dist/web/utils/variant_utils.js +1 -1
  190. package/dist/web/version.js +1 -1
  191. package/package.json +5 -3
@@ -14,11 +14,24 @@ export interface ExecuteCodeParams {
14
14
  /** The input of the code execution. */
15
15
  codeExecutionInput: CodeExecutionInput;
16
16
  }
17
+ /**
18
+ * A unique symbol to identify BaseCodeExecutor classes.
19
+ * Defined once and shared by all BaseCodeExecutor instances.
20
+ */
21
+ declare const BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL: unique symbol;
22
+ /**
23
+ * Type guard to check if an object is an instance of BaseCodeExecutor.
24
+ * @param obj The object to check.
25
+ * @returns True if the object is an instance of BaseCodeExecutor, false otherwise.
26
+ */
27
+ export declare function isBaseCodeExecutor(obj: unknown): obj is BaseCodeExecutor;
17
28
  /**
18
29
  * The code executor allows the agent to execute code blocks from model
19
30
  * responses and incorporate the execution results into the final response.
20
31
  */
21
32
  export declare abstract class BaseCodeExecutor {
33
+ /** A unique symbol to identify BaseCodeExecutor class. */
34
+ readonly [BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL] = true;
22
35
  /**
23
36
  * If true, extract and process data files from the model request
24
37
  * and attach them to the code executor.
@@ -58,3 +71,4 @@ export declare abstract class BaseCodeExecutor {
58
71
  */
59
72
  abstract executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
60
73
  }
74
+ export {};
@@ -1,6 +1,22 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
1
6
  import { LlmRequest } from '../models/llm_request.js';
2
7
  import { BaseCodeExecutor, ExecuteCodeParams } from './base_code_executor.js';
3
8
  import { CodeExecutionResult } from './code_execution_utils.js';
9
+ /**
10
+ * A unique symbol to identify BuiltInCodeExecutor classes.
11
+ * Defined once and shared by all BuiltInCodeExecutor instances.
12
+ */
13
+ declare const BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL: unique symbol;
14
+ /**
15
+ * Type guard to check if an object is an instance of BuiltInCodeExecutor.
16
+ * @param obj The object to check.
17
+ * @returns True if the object is an instance of BuiltInCodeExecutor, false otherwise.
18
+ */
19
+ export declare function isBuiltInCodeExecutor(obj: unknown): obj is BuiltInCodeExecutor;
4
20
  /**
5
21
  * A code executor that uses the Model's built-in code executor.
6
22
  *
@@ -8,6 +24,9 @@ import { CodeExecutionResult } from './code_execution_utils.js';
8
24
  * other models.
9
25
  */
10
26
  export declare class BuiltInCodeExecutor extends BaseCodeExecutor {
11
- executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
27
+ /** A unique symbol to identify BuiltInCodeExecutor class. */
28
+ readonly [BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL] = true;
29
+ executeCode(_params: ExecuteCodeParams): Promise<CodeExecutionResult>;
12
30
  processLlmRequest(llmRequest: LlmRequest): void;
13
31
  }
32
+ export {};
@@ -78,10 +78,8 @@ export declare class CodeExecutorContext {
78
78
  */
79
79
  updateCodeExecutionResult({ invocationId, code, resultStdout, resultStderr, }: UpdateCodeExecutionResultParams): void;
80
80
  /**
81
- * Gets the code executor context from the session state.
82
- * @param invocationId The session state to get the code executor context
83
- * from.
81
+ * Gets the code execution context from the session state.
84
82
  * @return The code execution context for the given invocation ID.
85
83
  */
86
- getCodeExecutionContext(invocationId: string): Record<string, unknown>;
84
+ getCodeExecutionContext(): Record<string, unknown>;
87
85
  }
@@ -3,27 +3,45 @@
3
3
  * Copyright 2025 Google LLC
4
4
  * SPDX-License-Identifier: Apache-2.0
5
5
  */
6
+ export { ActiveStreamingTool } from './agents/active_streaming_tool.js';
7
+ export type { ActiveStreamingToolParams } from './agents/active_streaming_tool.js';
6
8
  export { BaseAgent, isBaseAgent } from './agents/base_agent.js';
9
+ export type { AfterAgentCallback, BaseAgentConfig, BeforeAgentCallback, SingleAgentCallback, } from './agents/base_agent.js';
10
+ export { BaseLlmRequestProcessor, BaseLlmResponseProcessor, } from './agents/base_llm_processor.js';
7
11
  export { CallbackContext } from './agents/callback_context.js';
8
12
  export { functionsExportedForTestingOnly } from './agents/functions.js';
9
13
  export { InvocationContext } from './agents/invocation_context.js';
14
+ export type { InvocationContextParams } from './agents/invocation_context.js';
10
15
  export { LiveRequestQueue } from './agents/live_request_queue.js';
11
16
  export type { LiveRequest } from './agents/live_request_queue.js';
12
- export { LlmAgent } from './agents/llm_agent.js';
13
- export type { AfterModelCallback, AfterToolCallback, BeforeModelCallback, BeforeToolCallback, SingleAfterModelCallback, SingleAfterToolCallback, SingleBeforeModelCallback, SingleBeforeToolCallback } from './agents/llm_agent.js';
14
- export { LoopAgent } from './agents/loop_agent.js';
15
- export { ParallelAgent } from './agents/parallel_agent.js';
16
- export type { RunConfig } from './agents/run_config.js';
17
+ export { LlmAgent, isLlmAgent } from './agents/llm_agent.js';
18
+ export type { AfterModelCallback, AfterToolCallback, BeforeModelCallback, BeforeToolCallback, InstructionProvider, LlmAgentConfig, SingleAfterModelCallback, SingleAfterToolCallback, SingleBeforeModelCallback, SingleBeforeToolCallback, ToolUnion, } from './agents/llm_agent.js';
19
+ export { LoopAgent, isLoopAgent } from './agents/loop_agent.js';
20
+ export type { LoopAgentConfig } from './agents/loop_agent.js';
21
+ export { ParallelAgent, isParallelAgent } from './agents/parallel_agent.js';
22
+ export { ReadonlyContext } from './agents/readonly_context.js';
17
23
  export { StreamingMode } from './agents/run_config.js';
18
- export { SequentialAgent } from './agents/sequential_agent.js';
24
+ export type { RunConfig } from './agents/run_config.js';
25
+ export { SequentialAgent, isSequentialAgent } from './agents/sequential_agent.js';
26
+ export type { TranscriptionEntry } from './agents/transcription_entry.js';
19
27
  export { InMemoryArtifactService } from './artifacts/in_memory_artifact_service.js';
28
+ export { AuthCredentialTypes } from './auth/auth_credential.js';
29
+ export type { AuthCredential, HttpAuth, HttpCredentials, OAuth2Auth, ServiceAccount, ServiceAccountCredential, } from './auth/auth_credential.js';
30
+ export type { AuthScheme, OpenIdConnectWithConfig } from './auth/auth_schemes.js';
31
+ export type { AuthConfig } from './auth/auth_tool.js';
20
32
  export type { BaseCredentialService } from './auth/credential_service/base_credential_service.js';
33
+ export { BaseCodeExecutor } from './code_executors/base_code_executor.js';
34
+ export type { ExecuteCodeParams } from './code_executors/base_code_executor.js';
21
35
  export { BuiltInCodeExecutor } from './code_executors/built_in_code_executor.js';
22
- export { createEvent, getFunctionCalls, getFunctionResponses, hasTrailingCodeExecutionResult, isFinalResponse, stringifyContent } from './events/event.js';
36
+ export type { CodeExecutionInput, CodeExecutionResult, File, } from './code_executors/code_execution_utils.js';
37
+ export { createEvent, getFunctionCalls, getFunctionResponses, hasTrailingCodeExecutionResult, isFinalResponse, stringifyContent, } from './events/event.js';
23
38
  export type { Event } from './events/event.js';
24
- export type { EventActions } from './events/event_actions.js';
25
39
  export { createEventActions } from './events/event_actions.js';
40
+ export type { EventActions } from './events/event_actions.js';
41
+ export { BaseExampleProvider, isBaseExampleProvider, } from './examples/base_example_provider.js';
42
+ export type { Example } from './examples/example.js';
26
43
  export { InMemoryMemoryService } from './memory/in_memory_memory_service.js';
44
+ export type { MemoryEntry } from './memory/memory_entry.js';
27
45
  export { BaseLlm, isBaseLlm } from './models/base_llm.js';
28
46
  export type { BaseLlmConnection } from './models/base_llm_connection.js';
29
47
  export { Gemini } from './models/google_llm.js';
@@ -31,28 +49,35 @@ export type { GeminiParams } from './models/google_llm.js';
31
49
  export type { LlmRequest } from './models/llm_request.js';
32
50
  export type { LlmResponse } from './models/llm_response.js';
33
51
  export { LLMRegistry } from './models/registry.js';
52
+ export type { BaseLlmType } from './models/registry.js';
34
53
  export { BasePlugin } from './plugins/base_plugin.js';
35
54
  export { LoggingPlugin } from './plugins/logging_plugin.js';
36
55
  export { PluginManager } from './plugins/plugin_manager.js';
37
- export { getAskUserConfirmationFunctionCalls, InMemoryPolicyEngine, PolicyOutcome, REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, SecurityPlugin } from './plugins/security_plugin.js';
38
- export type { BasePolicyEngine, PolicyCheckResult, ToolCallPolicyContext } from './plugins/security_plugin.js';
56
+ export { InMemoryPolicyEngine, PolicyOutcome, REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, SecurityPlugin, getAskUserConfirmationFunctionCalls, } from './plugins/security_plugin.js';
57
+ export type { BasePolicyEngine, PolicyCheckResult, ToolCallPolicyContext, } from './plugins/security_plugin.js';
39
58
  export { InMemoryRunner } from './runner/in_memory_runner.js';
40
59
  export { Runner } from './runner/runner.js';
60
+ export type { RunnerConfig } from './runner/runner.js';
41
61
  export { InMemorySessionService } from './sessions/in_memory_session_service.js';
42
62
  export { createSession } from './sessions/session.js';
43
63
  export type { Session } from './sessions/session.js';
44
64
  export { State } from './sessions/state.js';
45
- export { AgentTool } from './tools/agent_tool.js';
46
- export { BaseTool } from './tools/base_tool.js';
65
+ export { AgentTool, isAgentTool } from './tools/agent_tool.js';
66
+ export type { AgentToolConfig } from './tools/agent_tool.js';
67
+ export { BaseTool, isBaseTool } from './tools/base_tool.js';
47
68
  export { BaseToolset } from './tools/base_toolset.js';
48
- export { FunctionTool } from './tools/function_tool.js';
49
- export { GOOGLE_SEARCH } from './tools/google_search_tool.js';
69
+ export type { ToolPredicate } from './tools/base_toolset.js';
70
+ export { FunctionTool, isFunctionTool } from './tools/function_tool.js';
71
+ export type { ToolExecuteArgument, ToolExecuteFunction, ToolInputParameters, ToolOptions, } from './tools/function_tool.js';
72
+ export { GOOGLE_SEARCH, GoogleSearchTool } from './tools/google_search_tool.js';
50
73
  export { LongRunningFunctionTool } from './tools/long_running_tool.js';
51
74
  export { ToolConfirmation } from './tools/tool_confirmation.js';
52
75
  export { ToolContext } from './tools/tool_context.js';
53
- export { LogLevel, setLogLevel } from './utils/logger.js';
76
+ export { LogLevel, getLogger, setLogLevel, setLogger } from './utils/logger.js';
77
+ export type { Logger } from './utils/logger.js';
54
78
  export { isGemini2OrAbove } from './utils/model_name.js';
55
79
  export { zodObjectToSchema } from './utils/simple_zod_to_json.js';
80
+ export { GoogleLLMVariant } from './utils/variant_utils.js';
56
81
  export { version } from './version.js';
57
82
  export * from './artifacts/base_artifact_service.js';
58
83
  export * from './memory/base_memory_service.js';
@@ -4,12 +4,27 @@
4
4
  * SPDX-License-Identifier: Apache-2.0
5
5
  */
6
6
  import { Example } from './example.js';
7
+ /**
8
+ * A unique symbol to identify ADK agent classes.
9
+ * Defined once and shared by all BaseExampleProvider instances.
10
+ */
11
+ declare const BASE_EXAMPLE_PROVIDER_SIGNATURE_SYMBOL: unique symbol;
12
+ /**
13
+ * Type guard to check if an object is an instance of BaseExampleProvider.
14
+ * @param obj The object to check.
15
+ * @returns True if the object is an instance of BaseExampleProvider, false otherwise.
16
+ */
17
+ export declare function isBaseExampleProvider(obj: unknown): obj is BaseExampleProvider;
7
18
  /**
8
19
  * Base class for example providers.
9
20
  *
10
21
  * This class defines the interface for providing examples for a given query.
11
22
  */
12
23
  export declare abstract class BaseExampleProvider {
24
+ /**
25
+ * A unique symbol to identify ADK example provider classes.
26
+ */
27
+ readonly [BASE_EXAMPLE_PROVIDER_SIGNATURE_SYMBOL] = true;
13
28
  /**
14
29
  * Returns a list of examples for a given query.
15
30
  *
@@ -18,3 +33,4 @@ export declare abstract class BaseExampleProvider {
18
33
  */
19
34
  abstract getExamples(query: string): Example[];
20
35
  }
36
+ export {};
@@ -3,10 +3,10 @@
3
3
  * Copyright 2025 Google LLC
4
4
  * SPDX-License-Identifier: Apache-2.0
5
5
  */
6
+ export * from './artifacts/gcs_artifact_service.js';
6
7
  export * from './common.js';
8
+ export * from './telemetry/google_cloud.js';
9
+ export * from './telemetry/setup.js';
7
10
  export * from './tools/mcp/mcp_session_manager.js';
8
11
  export * from './tools/mcp/mcp_tool.js';
9
12
  export * from './tools/mcp/mcp_toolset.js';
10
- export * from './artifacts/gcs_artifact_service.js';
11
- export * from './telemetry/setup.js';
12
- export * from './telemetry/google_cloud.js';
@@ -3,7 +3,7 @@
3
3
  * Copyright 2025 Google LLC
4
4
  * SPDX-License-Identifier: Apache-2.0
5
5
  */
6
- import { Content, Blob } from '@google/genai';
6
+ import { Blob, Content } from '@google/genai';
7
7
  import { LlmResponse } from './llm_response.js';
8
8
  /**
9
9
  * The base class for a live model connection.
@@ -46,7 +46,7 @@ export interface LlmResponse {
46
46
  * NOTE: the entire object must be JSON serializable.
47
47
  */
48
48
  customMetadata?: {
49
- [key: string]: any;
49
+ [key: string]: unknown;
50
50
  };
51
51
  /**
52
52
  * The usage metadata of the LlmResponse.
@@ -110,13 +110,13 @@ export declare abstract class BasePlugin {
110
110
  * This callback helps logging and modifying the user message before the
111
111
  * runner starts the invocation.
112
112
  *
113
- * @param invocationContext The context for the entire invocation.
114
- * @param userMessage The message content input by user.
113
+ * @param params.invocationContext The context for the entire invocation.
114
+ * @param params.userMessage The message content input by user.
115
115
  * @returns An optional `Content` to be returned to the ADK. Returning a
116
116
  * value to replace the user message. Returning `undefined` to proceed
117
117
  * normally.
118
118
  */
119
- onUserMessageCallback({ invocationContext, userMessage }: {
119
+ onUserMessageCallback(params: {
120
120
  invocationContext: InvocationContext;
121
121
  userMessage: Content;
122
122
  }): Promise<Content | undefined>;
@@ -126,13 +126,13 @@ export declare abstract class BasePlugin {
126
126
  * This is the first callback to be called in the lifecycle, ideal for global
127
127
  * setup or initialization tasks.
128
128
  *
129
- * @param invocationContext The context for the entire invocation, containing
129
+ * @param params.invocationContext The context for the entire invocation, containing
130
130
  * session information, the root agent, etc.
131
131
  * @returns An optional `Event` to be returned to the ADK. Returning a value
132
132
  * to halt execution of the runner and ends the runner with that event.
133
133
  * Return `undefined` to proceed normally.
134
134
  */
135
- beforeRunCallback({ invocationContext }: {
135
+ beforeRunCallback(params: {
136
136
  invocationContext: InvocationContext;
137
137
  }): Promise<Content | undefined>;
138
138
  /**
@@ -141,13 +141,13 @@ export declare abstract class BasePlugin {
141
141
  * This is the ideal place to make modification to the event before the event
142
142
  * is handled by the underlying agent app.
143
143
  *
144
- * @param invocationContext The context for the entire invocation.
145
- * @param event The event raised by the runner.
144
+ * @param params.invocationContext The context for the entire invocation.
145
+ * @param params.event The event raised by the runner.
146
146
  * @returns An optional value. A non-`undefined` return may be used by the
147
147
  * framework to modify or replace the response. Returning `undefined`
148
148
  * allows the original response to be used.
149
149
  */
150
- onEventCallback({ invocationContext, event }: {
150
+ onEventCallback(params: {
151
151
  invocationContext: InvocationContext;
152
152
  event: Event;
153
153
  }): Promise<Event | undefined>;
@@ -157,10 +157,10 @@ export declare abstract class BasePlugin {
157
157
  * This is the final callback in the ADK lifecycle, suitable for cleanup,
158
158
  * final logging, or reporting tasks.
159
159
  *
160
- * @param invocationContext The context for the entire invocation.
160
+ * @param params.invocationContext The context for the entire invocation.
161
161
  * @returns undefined
162
162
  */
163
- afterRunCallback({ invocationContext }: {
163
+ afterRunCallback(params: {
164
164
  invocationContext: InvocationContext;
165
165
  }): Promise<void>;
166
166
  /**
@@ -169,13 +169,13 @@ export declare abstract class BasePlugin {
169
169
  * This callback can be used for logging, setup, or to short-circuit the
170
170
  * agent's execution by returning a value.
171
171
  *
172
- * @param agent The agent that is about to run.
173
- * @param callbackContext The context for the agent invocation.
172
+ * @param params.agent The agent that is about to run.
173
+ * @param params.callbackContext The context for the agent invocation.
174
174
  * @returns An optional `Content` object. If a value is returned, it will
175
175
  * bypass the agent's callbacks and its execution, and return this value
176
176
  * directly. Returning `undefined` allows the agent to proceed normally.
177
177
  */
178
- beforeAgentCallback({ agent, callbackContext }: {
178
+ beforeAgentCallback(params: {
179
179
  agent: BaseAgent;
180
180
  callbackContext: CallbackContext;
181
181
  }): Promise<Content | undefined>;
@@ -185,13 +185,13 @@ export declare abstract class BasePlugin {
185
185
  * This callback can be used to inspect, log, or modify the agent's final
186
186
  * result before it is returned.
187
187
  *
188
- * @param agent The agent that has just run.
189
- * @param callbackContext The context for the agent invocation.
188
+ * @param params.agent The agent that has just run.
189
+ * @param params.callbackContext The context for the agent invocation.
190
190
  * @returns An optional `Content` object. If a value is returned, it will
191
191
  * replace the agent's original result. Returning `undefined` uses the
192
192
  * original, unmodified result.
193
193
  */
194
- afterAgentCallback({ agent, callbackContext }: {
194
+ afterAgentCallback(params: {
195
195
  agent: BaseAgent;
196
196
  callbackContext: CallbackContext;
197
197
  }): Promise<Content | undefined>;
@@ -202,13 +202,13 @@ export declare abstract class BasePlugin {
202
202
  * object. It can also be used to implement caching by returning a cached
203
203
  * `LlmResponse`, which would skip the actual model call.
204
204
  *
205
- * @param callbackContext The context for the current agent call.
206
- * @param llmRequest The prepared request object to be sent to the model.
205
+ * @param params.callbackContext The context for the current agent call.
206
+ * @param params.llmRequest The prepared request object to be sent to the model.
207
207
  * @returns An optional value. The interpretation of a non-`undefined`
208
208
  * trigger an early exit and returns the response immediately. Returning
209
209
  * `undefined` allows the LLM request to proceed normally.
210
210
  */
211
- beforeModelCallback({ callbackContext, llmRequest }: {
211
+ beforeModelCallback(params: {
212
212
  callbackContext: CallbackContext;
213
213
  llmRequest: LlmRequest;
214
214
  }): Promise<LlmResponse | undefined>;
@@ -218,13 +218,13 @@ export declare abstract class BasePlugin {
218
218
  * This is the ideal place to log model responses, collect metrics on token
219
219
  * usage, or perform post-processing on the raw `LlmResponse`.
220
220
  *
221
- * @param callbackContext The context for the current agent call.
222
- * @param llmResponse The response object received from the model.
221
+ * @param params.callbackContext The context for the current agent call.
222
+ * @param params.llmResponse The response object received from the model.
223
223
  * @returns An optional value. A non-`undefined` return may be used by the
224
224
  * framework to modify or replace the response. Returning `undefined`
225
225
  * allows the original response to be used.
226
226
  */
227
- afterModelCallback({ callbackContext, llmResponse }: {
227
+ afterModelCallback(params: {
228
228
  callbackContext: CallbackContext;
229
229
  llmResponse: LlmResponse;
230
230
  }): Promise<LlmResponse | undefined>;
@@ -234,15 +234,15 @@ export declare abstract class BasePlugin {
234
234
  * This callback provides an opportunity to handle model errors gracefully,
235
235
  * potentially providing alternative responses or recovery mechanisms.
236
236
  *
237
- * @param callbackContext The context for the current agent call.
238
- * @param llmRequest The request that was sent to the model when the error
237
+ * @param params.callbackContext The context for the current agent call.
238
+ * @param params.llmRequest The request that was sent to the model when the error
239
239
  * occurred.
240
- * @param error The exception that was raised during model execution.
240
+ * @param params.error The exception that was raised during model execution.
241
241
  * @returns An optional LlmResponse. If an LlmResponse is returned, it will be
242
242
  * used instead of propagating the error. Returning `undefined` allows
243
243
  * the original error to be raised.
244
244
  */
245
- onModelErrorCallback({ callbackContext, llmRequest, error }: {
245
+ onModelErrorCallback(params: {
246
246
  callbackContext: CallbackContext;
247
247
  llmRequest: LlmRequest;
248
248
  error: Error;
@@ -253,15 +253,15 @@ export declare abstract class BasePlugin {
253
253
  * This callback is useful for logging tool usage, input validation, or
254
254
  * modifying the arguments before they are passed to the tool.
255
255
  *
256
- * @param tool The tool instance that is about to be executed.
257
- * @param toolArgs The dictionary of arguments to be used for invoking the
256
+ * @param params.tool The tool instance that is about to be executed.
257
+ * @param params.toolArgs The dictionary of arguments to be used for invoking the
258
258
  * tool.
259
- * @param toolContext The context specific to the tool execution.
259
+ * @param params.toolContext The context specific to the tool execution.
260
260
  * @returns An optional dictionary. If a dictionary is returned, it will stop
261
261
  * the tool execution and return this response immediately. Returning
262
262
  * `undefined` uses the original, unmodified arguments.
263
263
  */
264
- beforeToolCallback({ tool, toolArgs, toolContext }: {
264
+ beforeToolCallback(params: {
265
265
  tool: BaseTool;
266
266
  toolArgs: Record<string, unknown>;
267
267
  toolContext: ToolContext;
@@ -272,36 +272,46 @@ export declare abstract class BasePlugin {
272
272
  * This callback allows for inspecting, logging, or modifying the result
273
273
  * returned by a tool.
274
274
  *
275
- * @param tool The tool instance that has just been executed.
276
- * @param toolArgs The original arguments that were passed to the tool.
277
- * @param toolContext The context specific to the tool execution.
278
- * @param result The dictionary returned by the tool invocation.
275
+ * @param params.tool The tool instance that has just been executed.
276
+ * @param params.toolArgs The original arguments that were passed to the tool.
277
+ * @param params.toolContext The context specific to the tool execution.
278
+ * @param params.result The dictionary returned by the tool invocation.
279
279
  * @returns An optional dictionary. If a dictionary is returned, it will
280
280
  * **replace** the original result from the tool. This allows for
281
281
  * post-processing or altering tool outputs. Returning `undefined` uses
282
282
  * the original, unmodified result.
283
283
  */
284
- afterToolCallback({ tool, toolArgs, toolContext, result }: {
284
+ afterToolCallback(params: {
285
285
  tool: BaseTool;
286
286
  toolArgs: Record<string, unknown>;
287
287
  toolContext: ToolContext;
288
288
  result: Record<string, unknown>;
289
289
  }): Promise<Record<string, unknown> | undefined>;
290
+ /**
291
+ * Callback executed when a tool call encounters an error.
292
+ tool: BaseTool;
293
+ toolArgs: Record<string, unknown>;
294
+ toolContext: ToolContext;
295
+ result: Record<string, unknown>;
296
+ }): Promise<Record<string, unknown> | undefined> {
297
+ return;
298
+ }
299
+
290
300
  /**
291
301
  * Callback executed when a tool call encounters an error.
292
302
  *
293
303
  * This callback provides an opportunity to handle tool errors gracefully,
294
304
  * potentially providing alternative responses or recovery mechanisms.
295
305
  *
296
- * @param tool The tool instance that encountered an error.
297
- * @param toolArgs The arguments that were passed to the tool.
298
- * @param toolContext The context specific to the tool execution.
299
- * @param error The exception that was raised during tool execution.
306
+ * @param params.tool The tool instance that encountered an error.
307
+ * @param params.toolArgs The arguments that were passed to the tool.
308
+ * @param params.toolContext The context specific to the tool execution.
309
+ * @param params.error The exception that was raised during tool execution.
300
310
  * @returns An optional dictionary. If a dictionary is returned, it will be
301
311
  * used as the tool response instead of propagating the error. Returning
302
312
  * `undefined` allows the original error to be raised.
303
313
  */
304
- onToolErrorCallback({ tool, toolArgs, toolContext, error }: {
314
+ onToolErrorCallback(params: {
305
315
  tool: BaseTool;
306
316
  toolArgs: Record<string, unknown>;
307
317
  toolContext: ToolContext;
@@ -46,53 +46,53 @@ export declare class LoggingPlugin extends BasePlugin {
46
46
  * @param name The name of the plugin instance.
47
47
  */
48
48
  constructor(name?: string);
49
- onUserMessageCallback({ invocationContext, userMessage }: {
49
+ onUserMessageCallback({ invocationContext, userMessage, }: {
50
50
  invocationContext: InvocationContext;
51
51
  userMessage: Content;
52
52
  }): Promise<Content | undefined>;
53
- beforeRunCallback({ invocationContext }: {
53
+ beforeRunCallback({ invocationContext, }: {
54
54
  invocationContext: InvocationContext;
55
55
  }): Promise<Content | undefined>;
56
- onEventCallback({ invocationContext, event }: {
56
+ onEventCallback({ event, }: {
57
57
  invocationContext: InvocationContext;
58
58
  event: Event;
59
59
  }): Promise<Event | undefined>;
60
- afterRunCallback({ invocationContext }: {
60
+ afterRunCallback({ invocationContext, }: {
61
61
  invocationContext: InvocationContext;
62
62
  }): Promise<void>;
63
- beforeAgentCallback({ agent, callbackContext }: {
63
+ beforeAgentCallback({ callbackContext, }: {
64
64
  agent: BaseAgent;
65
65
  callbackContext: CallbackContext;
66
66
  }): Promise<Content | undefined>;
67
- afterAgentCallback({ agent, callbackContext }: {
67
+ afterAgentCallback({ callbackContext, }: {
68
68
  agent: BaseAgent;
69
69
  callbackContext: CallbackContext;
70
70
  }): Promise<Content | undefined>;
71
- beforeModelCallback({ callbackContext, llmRequest }: {
71
+ beforeModelCallback({ callbackContext, llmRequest, }: {
72
72
  callbackContext: CallbackContext;
73
73
  llmRequest: LlmRequest;
74
74
  }): Promise<LlmResponse | undefined>;
75
- afterModelCallback({ callbackContext, llmResponse }: {
75
+ afterModelCallback({ callbackContext, llmResponse, }: {
76
76
  callbackContext: CallbackContext;
77
77
  llmResponse: LlmResponse;
78
78
  }): Promise<LlmResponse | undefined>;
79
- beforeToolCallback({ tool, toolArgs, toolContext }: {
79
+ beforeToolCallback({ tool, toolArgs, toolContext, }: {
80
80
  tool: BaseTool;
81
81
  toolArgs: Record<string, unknown>;
82
82
  toolContext: ToolContext;
83
83
  }): Promise<Record<string, unknown> | undefined>;
84
- afterToolCallback({ tool, toolArgs, toolContext, result }: {
84
+ afterToolCallback({ tool, toolContext, result, }: {
85
85
  tool: BaseTool;
86
86
  toolArgs: Record<string, unknown>;
87
87
  toolContext: ToolContext;
88
88
  result: Record<string, unknown>;
89
89
  }): Promise<Record<string, unknown> | undefined>;
90
- onModelErrorCallback({ callbackContext, llmRequest, error }: {
90
+ onModelErrorCallback({ callbackContext, error, }: {
91
91
  callbackContext: CallbackContext;
92
92
  llmRequest: LlmRequest;
93
93
  error: Error;
94
94
  }): Promise<LlmResponse | undefined>;
95
- onToolErrorCallback({ tool, toolArgs, toolContext, error }: {
95
+ onToolErrorCallback({ tool, toolArgs, toolContext, error, }: {
96
96
  tool: BaseTool;
97
97
  toolArgs: Record<string, unknown>;
98
98
  toolContext: ToolContext;
@@ -67,47 +67,47 @@ export declare class PluginManager {
67
67
  /**
68
68
  * Runs the `onUserMessageCallback` for all plugins.
69
69
  */
70
- runOnUserMessageCallback({ userMessage, invocationContext }: {
70
+ runOnUserMessageCallback({ userMessage, invocationContext, }: {
71
71
  userMessage: Content;
72
72
  invocationContext: InvocationContext;
73
73
  }): Promise<Content | undefined>;
74
74
  /**
75
75
  * Runs the `beforeRunCallback` for all plugins.
76
76
  */
77
- runBeforeRunCallback({ invocationContext }: {
77
+ runBeforeRunCallback({ invocationContext, }: {
78
78
  invocationContext: InvocationContext;
79
79
  }): Promise<Content | undefined>;
80
80
  /**
81
81
  * Runs the `afterRunCallback` for all plugins.
82
82
  */
83
- runAfterRunCallback({ invocationContext }: {
83
+ runAfterRunCallback({ invocationContext, }: {
84
84
  invocationContext: InvocationContext;
85
85
  }): Promise<void>;
86
86
  /**
87
87
  * Runs the `onEventCallback` for all plugins.
88
88
  */
89
- runOnEventCallback({ invocationContext, event }: {
89
+ runOnEventCallback({ invocationContext, event, }: {
90
90
  invocationContext: InvocationContext;
91
91
  event: Event;
92
92
  }): Promise<Event | undefined>;
93
93
  /**
94
94
  * Runs the `beforeAgentCallback` for all plugins.
95
95
  */
96
- runBeforeAgentCallback({ agent, callbackContext }: {
96
+ runBeforeAgentCallback({ agent, callbackContext, }: {
97
97
  agent: BaseAgent;
98
98
  callbackContext: CallbackContext;
99
99
  }): Promise<Content | undefined>;
100
100
  /**
101
101
  * Runs the `afterAgentCallback` for all plugins.
102
102
  */
103
- runAfterAgentCallback({ agent, callbackContext }: {
103
+ runAfterAgentCallback({ agent, callbackContext, }: {
104
104
  agent: BaseAgent;
105
105
  callbackContext: CallbackContext;
106
106
  }): Promise<Content | undefined>;
107
107
  /**
108
108
  * Runs the `beforeToolCallback` for all plugins.
109
109
  */
110
- runBeforeToolCallback({ tool, toolArgs, toolContext }: {
110
+ runBeforeToolCallback({ tool, toolArgs, toolContext, }: {
111
111
  tool: BaseTool;
112
112
  toolArgs: Record<string, unknown>;
113
113
  toolContext: ToolContext;
@@ -115,7 +115,7 @@ export declare class PluginManager {
115
115
  /**
116
116
  * Runs the `afterToolCallback` for all plugins.
117
117
  */
118
- runAfterToolCallback({ tool, toolArgs, toolContext, result }: {
118
+ runAfterToolCallback({ tool, toolArgs, toolContext, result, }: {
119
119
  tool: BaseTool;
120
120
  toolArgs: Record<string, unknown>;
121
121
  toolContext: ToolContext;
@@ -124,7 +124,7 @@ export declare class PluginManager {
124
124
  /**
125
125
  * Runs the `onModelErrorCallback` for all plugins.
126
126
  */
127
- runOnModelErrorCallback({ callbackContext, llmRequest, error }: {
127
+ runOnModelErrorCallback({ callbackContext, llmRequest, error, }: {
128
128
  callbackContext: CallbackContext;
129
129
  llmRequest: LlmRequest;
130
130
  error: Error;
@@ -132,21 +132,21 @@ export declare class PluginManager {
132
132
  /**
133
133
  * Runs the `beforeModelCallback` for all plugins.
134
134
  */
135
- runBeforeModelCallback({ callbackContext, llmRequest }: {
135
+ runBeforeModelCallback({ callbackContext, llmRequest, }: {
136
136
  callbackContext: CallbackContext;
137
137
  llmRequest: LlmRequest;
138
138
  }): Promise<LlmResponse | undefined>;
139
139
  /**
140
140
  * Runs the `afterModelCallback` for all plugins.
141
141
  */
142
- runAfterModelCallback({ callbackContext, llmResponse }: {
142
+ runAfterModelCallback({ callbackContext, llmResponse, }: {
143
143
  callbackContext: CallbackContext;
144
144
  llmResponse: LlmResponse;
145
145
  }): Promise<LlmResponse | undefined>;
146
146
  /**
147
147
  * Runs the `onToolErrorCallback` for all plugins.
148
148
  */
149
- runOnToolErrorCallback({ tool, toolArgs, toolContext, error }: {
149
+ runOnToolErrorCallback({ tool, toolArgs, toolContext, error, }: {
150
150
  tool: BaseTool;
151
151
  toolArgs: Record<string, unknown>;
152
152
  toolContext: ToolContext;
@@ -29,7 +29,7 @@ export interface BasePolicyEngine {
29
29
  evaluate(context: ToolCallPolicyContext): Promise<PolicyCheckResult>;
30
30
  }
31
31
  export declare class InMemoryPolicyEngine implements BasePolicyEngine {
32
- evaluate(context: ToolCallPolicyContext): Promise<PolicyCheckResult>;
32
+ evaluate(): Promise<PolicyCheckResult>;
33
33
  }
34
34
  /**
35
35
  * Security Plugin for running Orcas agents.