@paean-ai/adk 0.2.19 → 0.2.20

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 (254) hide show
  1. package/dist/cjs/agents/active_streaming_tool.js +44 -0
  2. package/dist/cjs/agents/base_agent.js +245 -0
  3. package/dist/cjs/agents/base_llm_processor.js +44 -0
  4. package/dist/cjs/agents/callback_context.js +98 -0
  5. package/dist/cjs/agents/content_processor_utils.js +311 -0
  6. package/dist/cjs/agents/functions.js +425 -0
  7. package/dist/cjs/agents/instructions.js +110 -0
  8. package/dist/cjs/agents/invocation_context.js +107 -0
  9. package/dist/cjs/agents/live_request_queue.js +136 -0
  10. package/dist/cjs/agents/llm_agent.js +1257 -0
  11. package/dist/cjs/agents/loop_agent.js +68 -0
  12. package/dist/cjs/agents/parallel_agent.js +78 -0
  13. package/dist/cjs/agents/readonly_context.js +68 -0
  14. package/dist/cjs/agents/run_config.js +70 -0
  15. package/dist/cjs/agents/sequential_agent.js +84 -0
  16. package/dist/cjs/agents/transcription_entry.js +27 -0
  17. package/dist/cjs/artifacts/base_artifact_service.js +27 -0
  18. package/dist/cjs/artifacts/gcs_artifact_service.js +140 -0
  19. package/dist/cjs/artifacts/in_memory_artifact_service.js +119 -0
  20. package/dist/cjs/auth/auth_credential.js +46 -0
  21. package/dist/cjs/auth/auth_handler.js +92 -0
  22. package/dist/cjs/auth/auth_schemes.js +62 -0
  23. package/dist/cjs/auth/auth_tool.js +27 -0
  24. package/dist/cjs/auth/credential_service/base_credential_service.js +27 -0
  25. package/dist/cjs/auth/credential_service/in_memory_credential_service.js +63 -0
  26. package/dist/cjs/auth/exchanger/base_credential_exchanger.js +40 -0
  27. package/dist/cjs/auth/exchanger/credential_exchanger_registry.js +59 -0
  28. package/dist/cjs/code_executors/base_code_executor.js +76 -0
  29. package/dist/cjs/code_executors/built_in_code_executor.js +58 -0
  30. package/dist/cjs/code_executors/code_execution_utils.js +142 -0
  31. package/dist/cjs/code_executors/code_executor_context.js +198 -0
  32. package/dist/cjs/common.js +181 -0
  33. package/dist/cjs/events/event.js +119 -0
  34. package/dist/cjs/events/event_actions.js +83 -0
  35. package/dist/cjs/examples/base_example_provider.js +40 -0
  36. package/dist/cjs/examples/example.js +27 -0
  37. package/dist/cjs/examples/example_util.js +107 -0
  38. package/dist/cjs/index.js +12 -12
  39. package/dist/cjs/index.js.map +3 -3
  40. package/dist/cjs/index_web.js +33 -0
  41. package/dist/cjs/memory/base_memory_service.js +27 -0
  42. package/dist/cjs/memory/in_memory_memory_service.js +97 -0
  43. package/dist/cjs/memory/memory_entry.js +27 -0
  44. package/dist/cjs/models/base_llm.js +95 -0
  45. package/dist/cjs/models/base_llm_connection.js +27 -0
  46. package/dist/cjs/models/gemini_llm_connection.js +132 -0
  47. package/dist/cjs/models/google_llm.js +472 -0
  48. package/dist/cjs/models/llm_request.js +82 -0
  49. package/dist/cjs/models/llm_response.js +71 -0
  50. package/dist/cjs/models/registry.js +121 -0
  51. package/dist/cjs/plugins/base_plugin.js +236 -0
  52. package/dist/cjs/plugins/logging_plugin.js +222 -0
  53. package/dist/cjs/plugins/plugin_manager.js +239 -0
  54. package/dist/cjs/plugins/security_plugin.js +153 -0
  55. package/dist/cjs/runner/in_memory_runner.js +58 -0
  56. package/dist/cjs/runner/runner.js +277 -0
  57. package/dist/cjs/sessions/base_session_service.js +71 -0
  58. package/dist/cjs/sessions/in_memory_session_service.js +184 -0
  59. package/dist/cjs/sessions/session.js +48 -0
  60. package/dist/cjs/sessions/state.js +101 -0
  61. package/dist/cjs/telemetry/google_cloud.js +85 -0
  62. package/dist/cjs/telemetry/setup.js +97 -0
  63. package/dist/cjs/telemetry/tracing.js +231 -0
  64. package/dist/cjs/tools/agent_tool.js +134 -0
  65. package/dist/cjs/tools/base_tool.js +107 -0
  66. package/dist/cjs/tools/base_toolset.js +76 -0
  67. package/dist/cjs/tools/forwarding_artifact_service.js +71 -0
  68. package/dist/cjs/tools/function_tool.js +101 -0
  69. package/dist/cjs/tools/google_search_tool.js +77 -0
  70. package/dist/cjs/tools/long_running_tool.js +63 -0
  71. package/dist/cjs/tools/mcp/mcp_session_manager.js +65 -0
  72. package/dist/cjs/tools/mcp/mcp_tool.js +65 -0
  73. package/dist/cjs/tools/mcp/mcp_toolset.js +61 -0
  74. package/dist/cjs/tools/tool_confirmation.js +49 -0
  75. package/dist/cjs/tools/tool_context.js +129 -0
  76. package/dist/cjs/utils/client_labels.js +56 -0
  77. package/dist/cjs/utils/deep_clone.js +44 -0
  78. package/dist/cjs/utils/env_aware_utils.js +83 -0
  79. package/dist/cjs/utils/gemini_schema_util.js +88 -0
  80. package/dist/cjs/utils/logger.js +121 -0
  81. package/dist/cjs/utils/model_name.js +76 -0
  82. package/dist/cjs/utils/simple_zod_to_json.js +191 -0
  83. package/dist/cjs/utils/variant_utils.js +55 -0
  84. package/dist/cjs/version.js +39 -0
  85. package/dist/esm/agents/active_streaming_tool.js +14 -0
  86. package/dist/esm/agents/base_agent.js +214 -0
  87. package/dist/esm/agents/base_llm_processor.js +13 -0
  88. package/dist/esm/agents/callback_context.js +68 -0
  89. package/dist/esm/agents/content_processor_utils.js +280 -0
  90. package/dist/esm/agents/functions.js +384 -0
  91. package/dist/esm/agents/instructions.js +80 -0
  92. package/dist/esm/agents/invocation_context.js +76 -0
  93. package/dist/esm/agents/live_request_queue.js +106 -0
  94. package/dist/esm/agents/llm_agent.js +1225 -0
  95. package/dist/esm/agents/loop_agent.js +38 -0
  96. package/dist/esm/agents/parallel_agent.js +48 -0
  97. package/dist/esm/agents/readonly_context.js +38 -0
  98. package/dist/esm/agents/run_config.js +39 -0
  99. package/dist/esm/agents/sequential_agent.js +54 -0
  100. package/dist/esm/agents/transcription_entry.js +5 -0
  101. package/dist/esm/artifacts/base_artifact_service.js +5 -0
  102. package/dist/esm/artifacts/gcs_artifact_service.js +110 -0
  103. package/dist/esm/artifacts/in_memory_artifact_service.js +89 -0
  104. package/dist/esm/auth/auth_credential.js +16 -0
  105. package/dist/esm/auth/auth_handler.js +62 -0
  106. package/dist/esm/auth/auth_schemes.js +31 -0
  107. package/dist/esm/auth/auth_tool.js +5 -0
  108. package/dist/esm/auth/credential_service/base_credential_service.js +5 -0
  109. package/dist/esm/auth/credential_service/in_memory_credential_service.js +33 -0
  110. package/dist/esm/auth/exchanger/base_credential_exchanger.js +10 -0
  111. package/dist/esm/auth/exchanger/credential_exchanger_registry.js +29 -0
  112. package/dist/esm/code_executors/base_code_executor.js +46 -0
  113. package/dist/esm/code_executors/built_in_code_executor.js +28 -0
  114. package/dist/esm/code_executors/code_execution_utils.js +108 -0
  115. package/dist/esm/code_executors/code_executor_context.js +168 -0
  116. package/dist/esm/common.js +98 -0
  117. package/dist/esm/events/event.js +83 -0
  118. package/dist/esm/events/event_actions.js +52 -0
  119. package/dist/esm/examples/base_example_provider.js +10 -0
  120. package/dist/esm/examples/example.js +5 -0
  121. package/dist/esm/examples/example_util.js +76 -0
  122. package/dist/esm/index.js +12 -12
  123. package/dist/esm/index.js.map +3 -3
  124. package/dist/esm/index_web.js +6 -0
  125. package/dist/esm/memory/base_memory_service.js +5 -0
  126. package/dist/esm/memory/in_memory_memory_service.js +67 -0
  127. package/dist/esm/memory/memory_entry.js +5 -0
  128. package/dist/esm/models/base_llm.js +64 -0
  129. package/dist/esm/models/base_llm_connection.js +5 -0
  130. package/dist/esm/models/gemini_llm_connection.js +102 -0
  131. package/dist/esm/models/google_llm.js +446 -0
  132. package/dist/esm/models/llm_request.js +50 -0
  133. package/dist/esm/models/llm_response.js +41 -0
  134. package/dist/esm/models/registry.js +91 -0
  135. package/dist/esm/plugins/base_plugin.js +206 -0
  136. package/dist/esm/plugins/logging_plugin.js +192 -0
  137. package/dist/esm/plugins/plugin_manager.js +209 -0
  138. package/dist/esm/plugins/security_plugin.js +119 -0
  139. package/dist/esm/runner/in_memory_runner.js +28 -0
  140. package/dist/esm/runner/runner.js +247 -0
  141. package/dist/esm/sessions/base_session_service.js +41 -0
  142. package/dist/esm/sessions/in_memory_session_service.js +154 -0
  143. package/dist/esm/sessions/session.js +18 -0
  144. package/dist/esm/sessions/state.js +71 -0
  145. package/dist/esm/telemetry/google_cloud.js +54 -0
  146. package/dist/esm/telemetry/setup.js +67 -0
  147. package/dist/esm/telemetry/tracing.js +195 -0
  148. package/dist/esm/tools/agent_tool.js +104 -0
  149. package/dist/esm/tools/base_tool.js +77 -0
  150. package/dist/esm/tools/base_toolset.js +46 -0
  151. package/dist/esm/tools/forwarding_artifact_service.js +41 -0
  152. package/dist/esm/tools/function_tool.js +71 -0
  153. package/dist/esm/tools/google_search_tool.js +47 -0
  154. package/dist/esm/tools/long_running_tool.js +33 -0
  155. package/dist/esm/tools/mcp/mcp_session_manager.js +35 -0
  156. package/dist/esm/tools/mcp/mcp_tool.js +35 -0
  157. package/dist/esm/tools/mcp/mcp_toolset.js +31 -0
  158. package/dist/esm/tools/tool_confirmation.js +19 -0
  159. package/dist/esm/tools/tool_context.js +99 -0
  160. package/dist/esm/utils/client_labels.js +26 -0
  161. package/dist/esm/utils/deep_clone.js +14 -0
  162. package/dist/esm/utils/env_aware_utils.js +49 -0
  163. package/dist/esm/utils/gemini_schema_util.js +58 -0
  164. package/dist/esm/utils/logger.js +89 -0
  165. package/dist/esm/utils/model_name.js +41 -0
  166. package/dist/esm/utils/simple_zod_to_json.js +160 -0
  167. package/dist/esm/utils/variant_utils.js +24 -0
  168. package/dist/esm/version.js +9 -0
  169. package/dist/types/models/google_llm.d.ts +0 -7
  170. package/dist/web/agents/active_streaming_tool.js +14 -0
  171. package/dist/web/agents/base_agent.js +265 -0
  172. package/dist/web/agents/base_llm_processor.js +13 -0
  173. package/dist/web/agents/callback_context.js +68 -0
  174. package/dist/web/agents/content_processor_utils.js +280 -0
  175. package/dist/web/agents/functions.js +384 -0
  176. package/dist/web/agents/instructions.js +80 -0
  177. package/dist/web/agents/invocation_context.js +76 -0
  178. package/dist/web/agents/live_request_queue.js +124 -0
  179. package/dist/web/agents/llm_agent.js +1355 -0
  180. package/dist/web/agents/loop_agent.js +71 -0
  181. package/dist/web/agents/parallel_agent.js +83 -0
  182. package/dist/web/agents/readonly_context.js +38 -0
  183. package/dist/web/agents/run_config.js +54 -0
  184. package/dist/web/agents/sequential_agent.js +99 -0
  185. package/dist/web/agents/transcription_entry.js +5 -0
  186. package/dist/web/artifacts/base_artifact_service.js +5 -0
  187. package/dist/web/artifacts/gcs_artifact_service.js +126 -0
  188. package/dist/web/artifacts/in_memory_artifact_service.js +89 -0
  189. package/dist/web/auth/auth_credential.js +16 -0
  190. package/dist/web/auth/auth_handler.js +62 -0
  191. package/dist/web/auth/auth_schemes.js +31 -0
  192. package/dist/web/auth/auth_tool.js +5 -0
  193. package/dist/web/auth/credential_service/base_credential_service.js +5 -0
  194. package/dist/web/auth/credential_service/in_memory_credential_service.js +33 -0
  195. package/dist/web/auth/exchanger/base_credential_exchanger.js +10 -0
  196. package/dist/web/auth/exchanger/credential_exchanger_registry.js +29 -0
  197. package/dist/web/code_executors/base_code_executor.js +46 -0
  198. package/dist/web/code_executors/built_in_code_executor.js +28 -0
  199. package/dist/web/code_executors/code_execution_utils.js +105 -0
  200. package/dist/web/code_executors/code_executor_context.js +168 -0
  201. package/dist/web/common.js +98 -0
  202. package/dist/web/events/event.js +101 -0
  203. package/dist/web/events/event_actions.js +67 -0
  204. package/dist/web/examples/base_example_provider.js +10 -0
  205. package/dist/web/examples/example.js +5 -0
  206. package/dist/web/examples/example_util.js +75 -0
  207. package/dist/web/index.js +1 -1
  208. package/dist/web/index.js.map +3 -3
  209. package/dist/web/index_web.js +6 -0
  210. package/dist/web/memory/base_memory_service.js +5 -0
  211. package/dist/web/memory/in_memory_memory_service.js +67 -0
  212. package/dist/web/memory/memory_entry.js +5 -0
  213. package/dist/web/models/base_llm.js +64 -0
  214. package/dist/web/models/base_llm_connection.js +5 -0
  215. package/dist/web/models/gemini_llm_connection.js +120 -0
  216. package/dist/web/models/google_llm.js +487 -0
  217. package/dist/web/models/llm_request.js +50 -0
  218. package/dist/web/models/llm_response.js +41 -0
  219. package/dist/web/models/registry.js +91 -0
  220. package/dist/web/plugins/base_plugin.js +206 -0
  221. package/dist/web/plugins/logging_plugin.js +192 -0
  222. package/dist/web/plugins/plugin_manager.js +209 -0
  223. package/dist/web/plugins/security_plugin.js +119 -0
  224. package/dist/web/runner/in_memory_runner.js +28 -0
  225. package/dist/web/runner/runner.js +278 -0
  226. package/dist/web/sessions/base_session_service.js +41 -0
  227. package/dist/web/sessions/in_memory_session_service.js +154 -0
  228. package/dist/web/sessions/session.js +18 -0
  229. package/dist/web/sessions/state.js +87 -0
  230. package/dist/web/telemetry/google_cloud.js +54 -0
  231. package/dist/web/telemetry/setup.js +67 -0
  232. package/dist/web/telemetry/tracing.js +210 -0
  233. package/dist/web/tools/agent_tool.js +118 -0
  234. package/dist/web/tools/base_tool.js +77 -0
  235. package/dist/web/tools/base_toolset.js +46 -0
  236. package/dist/web/tools/forwarding_artifact_service.js +41 -0
  237. package/dist/web/tools/function_tool.js +71 -0
  238. package/dist/web/tools/google_search_tool.js +47 -0
  239. package/dist/web/tools/long_running_tool.js +50 -0
  240. package/dist/web/tools/mcp/mcp_session_manager.js +35 -0
  241. package/dist/web/tools/mcp/mcp_tool.js +35 -0
  242. package/dist/web/tools/mcp/mcp_toolset.js +31 -0
  243. package/dist/web/tools/tool_confirmation.js +19 -0
  244. package/dist/web/tools/tool_context.js +99 -0
  245. package/dist/web/utils/client_labels.js +26 -0
  246. package/dist/web/utils/deep_clone.js +14 -0
  247. package/dist/web/utils/env_aware_utils.js +49 -0
  248. package/dist/web/utils/gemini_schema_util.js +58 -0
  249. package/dist/web/utils/logger.js +89 -0
  250. package/dist/web/utils/model_name.js +41 -0
  251. package/dist/web/utils/simple_zod_to_json.js +174 -0
  252. package/dist/web/utils/variant_utils.js +24 -0
  253. package/dist/web/version.js +9 -0
  254. package/package.json +1 -1
@@ -0,0 +1,154 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { deepClone } from "../utils/deep_clone.js";
7
+ import { randomUUID } from "../utils/env_aware_utils.js";
8
+ import { logger } from "../utils/logger.js";
9
+ import { BaseSessionService } from "./base_session_service.js";
10
+ import { createSession } from "./session.js";
11
+ import { State } from "./state.js";
12
+ class InMemorySessionService extends BaseSessionService {
13
+ constructor() {
14
+ super(...arguments);
15
+ /**
16
+ * A map from app name to a map from user ID to a map from session ID to
17
+ * session.
18
+ */
19
+ this.sessions = {};
20
+ /**
21
+ * A map from app name to a map from user ID to a map from key to the value.
22
+ */
23
+ this.userState = {};
24
+ /**
25
+ * A map from app name to a map from key to the value.
26
+ */
27
+ this.appState = {};
28
+ }
29
+ createSession({ appName, userId, state, sessionId }) {
30
+ const session = createSession({
31
+ id: sessionId || randomUUID(),
32
+ appName,
33
+ userId,
34
+ state,
35
+ events: [],
36
+ lastUpdateTime: Date.now()
37
+ });
38
+ if (!this.sessions[appName]) {
39
+ this.sessions[appName] = {};
40
+ }
41
+ if (!this.sessions[appName][userId]) {
42
+ this.sessions[appName][userId] = {};
43
+ }
44
+ this.sessions[appName][userId][session.id] = session;
45
+ return Promise.resolve(
46
+ this.mergeState(appName, userId, deepClone(session))
47
+ );
48
+ }
49
+ getSession({ appName, userId, sessionId, config }) {
50
+ if (!this.sessions[appName] || !this.sessions[appName][userId] || !this.sessions[appName][userId][sessionId]) {
51
+ return Promise.resolve(void 0);
52
+ }
53
+ const session = this.sessions[appName][userId][sessionId];
54
+ const copiedSession = deepClone(session);
55
+ if (config) {
56
+ if (config.numRecentEvents) {
57
+ copiedSession.events = copiedSession.events.slice(-config.numRecentEvents);
58
+ }
59
+ if (config.afterTimestamp) {
60
+ let i = copiedSession.events.length - 1;
61
+ while (i >= 0) {
62
+ if (copiedSession.events[i].timestamp < config.afterTimestamp) {
63
+ break;
64
+ }
65
+ i--;
66
+ }
67
+ if (i >= 0) {
68
+ copiedSession.events = copiedSession.events.slice(i + 1);
69
+ }
70
+ }
71
+ }
72
+ return Promise.resolve(this.mergeState(appName, userId, copiedSession));
73
+ }
74
+ listSessions({ appName, userId }) {
75
+ if (!this.sessions[appName] || !this.sessions[appName][userId]) {
76
+ return Promise.resolve({ sessions: [] });
77
+ }
78
+ const sessionsWithoutEvents = [];
79
+ for (const session of Object.values(this.sessions[appName][userId])) {
80
+ sessionsWithoutEvents.push(createSession({
81
+ id: session.id,
82
+ appName: session.appName,
83
+ userId: session.userId,
84
+ state: {},
85
+ events: [],
86
+ lastUpdateTime: session.lastUpdateTime
87
+ }));
88
+ }
89
+ return Promise.resolve({ sessions: sessionsWithoutEvents });
90
+ }
91
+ async deleteSession({ appName, userId, sessionId }) {
92
+ const session = await this.getSession({ appName, userId, sessionId });
93
+ if (!session) {
94
+ return;
95
+ }
96
+ delete this.sessions[appName][userId][sessionId];
97
+ }
98
+ async appendEvent({ session, event }) {
99
+ await super.appendEvent({ session, event });
100
+ session.lastUpdateTime = event.timestamp;
101
+ const appName = session.appName;
102
+ const userId = session.userId;
103
+ const sessionId = session.id;
104
+ const warning = (message) => {
105
+ logger.warn(`Failed to append event to session ${sessionId}: ${message}`);
106
+ };
107
+ if (!this.sessions[appName]) {
108
+ warning(`appName ${appName} not in sessions`);
109
+ return event;
110
+ }
111
+ if (!this.sessions[appName][userId]) {
112
+ warning(`userId ${userId} not in sessions[appName]`);
113
+ return event;
114
+ }
115
+ if (!this.sessions[appName][userId][sessionId]) {
116
+ warning(`sessionId ${sessionId} not in sessions[appName][userId]`);
117
+ return event;
118
+ }
119
+ if (event.actions && event.actions.stateDelta) {
120
+ for (const key of Object.keys(event.actions.stateDelta)) {
121
+ if (key.startsWith(State.APP_PREFIX)) {
122
+ this.appState[appName] = this.appState[appName] || {};
123
+ this.appState[appName][key.replace(State.APP_PREFIX, "")] = event.actions.stateDelta[key];
124
+ }
125
+ if (key.startsWith(State.USER_PREFIX)) {
126
+ this.userState[appName] = this.userState[appName] || {};
127
+ this.userState[appName][userId] = this.userState[appName][userId] || {};
128
+ this.userState[appName][userId][key.replace(State.USER_PREFIX, "")] = event.actions.stateDelta[key];
129
+ }
130
+ }
131
+ }
132
+ const storageSession = this.sessions[appName][userId][sessionId];
133
+ await super.appendEvent({ session: storageSession, event });
134
+ storageSession.lastUpdateTime = event.timestamp;
135
+ return event;
136
+ }
137
+ mergeState(appName, userId, copiedSession) {
138
+ if (this.appState[appName]) {
139
+ for (const key of Object.keys(this.appState[appName])) {
140
+ copiedSession.state[State.APP_PREFIX + key] = this.appState[appName][key];
141
+ }
142
+ }
143
+ if (!this.userState[appName] || !this.userState[appName][userId]) {
144
+ return copiedSession;
145
+ }
146
+ for (const key of Object.keys(this.userState[appName][userId])) {
147
+ copiedSession.state[State.USER_PREFIX + key] = this.userState[appName][userId][key];
148
+ }
149
+ return copiedSession;
150
+ }
151
+ }
152
+ export {
153
+ InMemorySessionService
154
+ };
@@ -0,0 +1,18 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ function createSession(params) {
7
+ return {
8
+ id: params.id,
9
+ appName: params.appName,
10
+ userId: params.userId || "",
11
+ state: params.state || {},
12
+ events: params.events || [],
13
+ lastUpdateTime: params.lastUpdateTime || 0
14
+ };
15
+ }
16
+ export {
17
+ createSession
18
+ };
@@ -0,0 +1,71 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ class State {
7
+ constructor(value = {}, delta = {}) {
8
+ this.value = value;
9
+ this.delta = delta;
10
+ }
11
+ /**
12
+ * Returns the value of the state dict for the given key.
13
+ *
14
+ * @param key The key to get the value for.
15
+ * @param defaultValue The default value to return if the key is not found.
16
+ * @return The value of the state for the given key, or the default value if
17
+ * not found.
18
+ */
19
+ get(key, defaultValue) {
20
+ if (key in this.delta) {
21
+ return this.delta[key];
22
+ }
23
+ if (key in this.value) {
24
+ return this.value[key];
25
+ }
26
+ return defaultValue;
27
+ }
28
+ /**
29
+ * Sets the value of the state dict for the given key.
30
+ *
31
+ * @param key The key to set the value for.
32
+ * @param value The value to set.
33
+ */
34
+ set(key, value) {
35
+ this.value[key] = value;
36
+ this.delta[key] = value;
37
+ }
38
+ /**
39
+ * Whether the state has pending delta.
40
+ */
41
+ has(key) {
42
+ return key in this.value || key in this.delta;
43
+ }
44
+ /**
45
+ * Whether the state has pending delta.
46
+ */
47
+ hasDelta() {
48
+ return Object.keys(this.delta).length > 0;
49
+ }
50
+ /**
51
+ * Updates the state dict with the given delta.
52
+ *
53
+ * @param delta The delta to update the state with.
54
+ */
55
+ update(delta) {
56
+ this.delta = { ...this.delta, ...delta };
57
+ this.value = { ...this.value, ...delta };
58
+ }
59
+ /**
60
+ * Returns the state as a plain JSON object.
61
+ */
62
+ toRecord() {
63
+ return { ...this.value, ...this.delta };
64
+ }
65
+ }
66
+ State.APP_PREFIX = "app:";
67
+ State.USER_PREFIX = "user:";
68
+ State.TEMP_PREFIX = "temp:";
69
+ export {
70
+ State
71
+ };
@@ -0,0 +1,54 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { GoogleAuth } from "google-auth-library";
7
+ import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
8
+ import { detectResources } from "@opentelemetry/resources";
9
+ import { gcpDetector } from "@opentelemetry/resource-detector-gcp";
10
+ import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";
11
+ import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
12
+ import { MetricExporter } from "@google-cloud/opentelemetry-cloud-monitoring-exporter";
13
+ import { logger } from "../utils/logger.js";
14
+ const GCP_PROJECT_ERROR_MESSAGE = "Cannot determine GCP Project. OTel GCP Exporters cannot be set up. Please make sure to log into correct GCP Project.";
15
+ async function getGcpProjectId() {
16
+ try {
17
+ const auth = new GoogleAuth();
18
+ const projectId = await auth.getProjectId();
19
+ return projectId || void 0;
20
+ } catch (error) {
21
+ return void 0;
22
+ }
23
+ }
24
+ async function getGcpExporters(config = {}) {
25
+ const {
26
+ enableTracing = false,
27
+ enableMetrics = false
28
+ // enableCloudLogging = false,
29
+ } = config;
30
+ const projectId = await getGcpProjectId();
31
+ if (!projectId) {
32
+ logger.warn(GCP_PROJECT_ERROR_MESSAGE);
33
+ return {};
34
+ }
35
+ return {
36
+ spanProcessors: enableTracing ? [
37
+ new BatchSpanProcessor(new TraceExporter({ projectId }))
38
+ ] : [],
39
+ metricReaders: enableMetrics ? [
40
+ new PeriodicExportingMetricReader({
41
+ exporter: new MetricExporter({ projectId }),
42
+ exportIntervalMillis: 5e3
43
+ })
44
+ ] : [],
45
+ logRecordProcessors: []
46
+ };
47
+ }
48
+ function getGcpResource() {
49
+ return detectResources({ detectors: [gcpDetector] });
50
+ }
51
+ export {
52
+ getGcpExporters,
53
+ getGcpResource
54
+ };
@@ -0,0 +1,67 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { trace, metrics } from "@opentelemetry/api";
7
+ import { logs } from "@opentelemetry/api-logs";
8
+ import { LoggerProvider, BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
9
+ import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
10
+ import { detectResources } from "@opentelemetry/resources";
11
+ import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
12
+ import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
13
+ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
14
+ import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
15
+ import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
16
+ function maybeSetOtelProviders(otelHooksToSetup = [], otelResource) {
17
+ const resource = otelResource || getOtelResource();
18
+ const allHooks = [...otelHooksToSetup, getOtelExporters()];
19
+ const spanProcessors = allHooks.flatMap((hooks) => hooks.spanProcessors || []);
20
+ const metricReaders = allHooks.flatMap((hooks) => hooks.metricReaders || []);
21
+ const logRecordProcessors = allHooks.flatMap((hooks) => hooks.logRecordProcessors || []);
22
+ if (spanProcessors.length > 0) {
23
+ const tracerProvider = new NodeTracerProvider({
24
+ resource,
25
+ spanProcessors
26
+ });
27
+ tracerProvider.register();
28
+ trace.setGlobalTracerProvider(tracerProvider);
29
+ }
30
+ if (metricReaders.length > 0) {
31
+ const meterProvider = new MeterProvider({
32
+ readers: metricReaders,
33
+ resource
34
+ });
35
+ metrics.setGlobalMeterProvider(meterProvider);
36
+ }
37
+ if (logRecordProcessors.length > 0) {
38
+ const loggerProvider = new LoggerProvider({
39
+ resource,
40
+ processors: logRecordProcessors
41
+ });
42
+ logs.setGlobalLoggerProvider(loggerProvider);
43
+ }
44
+ }
45
+ function getOtelResource() {
46
+ return detectResources({
47
+ detectors: []
48
+ });
49
+ }
50
+ function getOtelExportersConfig() {
51
+ return {
52
+ enableTracing: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT),
53
+ enableMetrics: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT),
54
+ enableLogging: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT)
55
+ };
56
+ }
57
+ function getOtelExporters(config = getOtelExportersConfig()) {
58
+ const { enableTracing, enableMetrics, enableLogging } = config;
59
+ return {
60
+ spanProcessors: enableTracing ? [new BatchSpanProcessor(new OTLPTraceExporter())] : [],
61
+ metricReaders: enableMetrics ? [new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() })] : [],
62
+ logRecordProcessors: enableLogging ? [new BatchLogRecordProcessor(new OTLPLogExporter())] : []
63
+ };
64
+ }
65
+ export {
66
+ maybeSetOtelProviders
67
+ };
@@ -0,0 +1,195 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { trace, context } from "@opentelemetry/api";
7
+ import { version } from "../version.js";
8
+ const GEN_AI_AGENT_DESCRIPTION = "gen_ai.agent.description";
9
+ const GEN_AI_AGENT_NAME = "gen_ai.agent.name";
10
+ const GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id";
11
+ const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
12
+ const GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
13
+ const GEN_AI_TOOL_DESCRIPTION = "gen_ai.tool.description";
14
+ const GEN_AI_TOOL_NAME = "gen_ai.tool.name";
15
+ const GEN_AI_TOOL_TYPE = "gen_ai.tool.type";
16
+ const tracer = trace.getTracer(
17
+ "gcp.vertex.agent",
18
+ version
19
+ );
20
+ function safeJsonSerialize(obj) {
21
+ try {
22
+ return JSON.stringify(obj);
23
+ } catch (error) {
24
+ return "<not serializable>";
25
+ }
26
+ }
27
+ function traceAgentInvocation({
28
+ agent,
29
+ invocationContext
30
+ }) {
31
+ const span = trace.getActiveSpan();
32
+ if (!span) return;
33
+ span.setAttributes({
34
+ [GEN_AI_OPERATION_NAME]: "invoke_agent",
35
+ // Conditionally Required
36
+ [GEN_AI_AGENT_DESCRIPTION]: agent.description,
37
+ [GEN_AI_AGENT_NAME]: agent.name,
38
+ [GEN_AI_CONVERSATION_ID]: invocationContext.session.id
39
+ });
40
+ }
41
+ function traceToolCall({
42
+ tool,
43
+ args,
44
+ functionResponseEvent
45
+ }) {
46
+ var _a, _b;
47
+ const span = trace.getActiveSpan();
48
+ if (!span) return;
49
+ span.setAttributes({
50
+ [GEN_AI_OPERATION_NAME]: "execute_tool",
51
+ [GEN_AI_TOOL_DESCRIPTION]: tool.description || "",
52
+ [GEN_AI_TOOL_NAME]: tool.name,
53
+ // e.g. FunctionTool
54
+ [GEN_AI_TOOL_TYPE]: tool.constructor.name,
55
+ // Setting empty llm request and response (as UI expect these) while not
56
+ // applicable for tool_response.
57
+ "gcp.vertex.agent.llm_request": "{}",
58
+ "gcp.vertex.agent.llm_response": "{}",
59
+ "gcp.vertex.agent.tool_call_args": shouldAddRequestResponseToSpans() ? safeJsonSerialize(args) : "{}"
60
+ });
61
+ let toolCallId = "<not specified>";
62
+ let toolResponse = "<not specified>";
63
+ if ((_a = functionResponseEvent.content) == null ? void 0 : _a.parts) {
64
+ const responseParts = functionResponseEvent.content.parts;
65
+ const functionResponse = (_b = responseParts[0]) == null ? void 0 : _b.functionResponse;
66
+ if (functionResponse == null ? void 0 : functionResponse.id) {
67
+ toolCallId = functionResponse.id;
68
+ }
69
+ if (functionResponse == null ? void 0 : functionResponse.response) {
70
+ toolResponse = functionResponse.response;
71
+ }
72
+ }
73
+ if (typeof toolResponse !== "object" || toolResponse === null) {
74
+ toolResponse = { result: toolResponse };
75
+ }
76
+ span.setAttributes({
77
+ [GEN_AI_TOOL_CALL_ID]: toolCallId,
78
+ "gcp.vertex.agent.event_id": functionResponseEvent.id,
79
+ "gcp.vertex.agent.tool_response": shouldAddRequestResponseToSpans() ? safeJsonSerialize(toolResponse) : "{}"
80
+ });
81
+ }
82
+ function traceMergedToolCalls({
83
+ responseEventId,
84
+ functionResponseEvent
85
+ }) {
86
+ const span = trace.getActiveSpan();
87
+ if (!span) return;
88
+ span.setAttributes({
89
+ [GEN_AI_OPERATION_NAME]: "execute_tool",
90
+ [GEN_AI_TOOL_NAME]: "(merged tools)",
91
+ [GEN_AI_TOOL_DESCRIPTION]: "(merged tools)",
92
+ [GEN_AI_TOOL_CALL_ID]: responseEventId,
93
+ "gcp.vertex.agent.tool_call_args": "N/A",
94
+ "gcp.vertex.agent.event_id": responseEventId,
95
+ // Setting empty llm request and response (as UI expect these) while not
96
+ // applicable for tool_response.
97
+ "gcp.vertex.agent.llm_request": "{}",
98
+ "gcp.vertex.agent.llm_response": "{}"
99
+ });
100
+ span.setAttribute("gcp.vertex.agent.tool_response", shouldAddRequestResponseToSpans() ? safeJsonSerialize(functionResponseEvent) : "{}");
101
+ }
102
+ function traceCallLlm({
103
+ invocationContext,
104
+ eventId,
105
+ llmRequest,
106
+ llmResponse
107
+ }) {
108
+ var _a, _b, _c;
109
+ const span = trace.getActiveSpan();
110
+ if (!span) return;
111
+ span.setAttributes({
112
+ "gen_ai.system": "gcp.vertex.agent",
113
+ "gen_ai.request.model": llmRequest.model,
114
+ "gcp.vertex.agent.invocation_id": invocationContext.invocationId,
115
+ "gcp.vertex.agent.session_id": invocationContext.session.id,
116
+ "gcp.vertex.agent.event_id": eventId,
117
+ // Consider removing once GenAI SDK provides a way to record this info.
118
+ "gcp.vertex.agent.llm_request": shouldAddRequestResponseToSpans() ? safeJsonSerialize(buildLlmRequestForTrace(llmRequest)) : "{}"
119
+ });
120
+ if ((_a = llmRequest.config) == null ? void 0 : _a.topP) {
121
+ span.setAttribute("gen_ai.request.top_p", llmRequest.config.topP);
122
+ }
123
+ if (((_b = llmRequest.config) == null ? void 0 : _b.maxOutputTokens) !== void 0) {
124
+ span.setAttribute("gen_ai.request.max_tokens", llmRequest.config.maxOutputTokens);
125
+ }
126
+ span.setAttribute("gcp.vertex.agent.llm_response", shouldAddRequestResponseToSpans() ? safeJsonSerialize(llmResponse) : "{}");
127
+ if (llmResponse.usageMetadata) {
128
+ span.setAttribute("gen_ai.usage.input_tokens", llmResponse.usageMetadata.promptTokenCount || 0);
129
+ }
130
+ if ((_c = llmResponse.usageMetadata) == null ? void 0 : _c.candidatesTokenCount) {
131
+ span.setAttribute("gen_ai.usage.output_tokens", llmResponse.usageMetadata.candidatesTokenCount);
132
+ }
133
+ if (llmResponse.finishReason) {
134
+ const finishReasonValue = typeof llmResponse.finishReason === "string" ? llmResponse.finishReason.toLowerCase() : String(llmResponse.finishReason).toLowerCase();
135
+ span.setAttribute("gen_ai.response.finish_reasons", [finishReasonValue]);
136
+ }
137
+ }
138
+ function traceSendData({
139
+ invocationContext,
140
+ eventId,
141
+ data
142
+ }) {
143
+ const span = trace.getActiveSpan();
144
+ if (!span) return;
145
+ span.setAttributes({
146
+ "gcp.vertex.agent.invocation_id": invocationContext.invocationId,
147
+ "gcp.vertex.agent.event_id": eventId
148
+ });
149
+ span.setAttribute("gcp.vertex.agent.data", shouldAddRequestResponseToSpans() ? safeJsonSerialize(data) : "{}");
150
+ }
151
+ function buildLlmRequestForTrace(llmRequest) {
152
+ const result = {
153
+ model: llmRequest.model,
154
+ contents: []
155
+ };
156
+ if (llmRequest.config) {
157
+ const { responseSchema, ...cleanConfig } = llmRequest.config;
158
+ result.config = cleanConfig;
159
+ }
160
+ result.contents = llmRequest.contents.map((content) => {
161
+ var _a;
162
+ return {
163
+ role: content.role,
164
+ parts: ((_a = content.parts) == null ? void 0 : _a.filter((part) => !part.inlineData)) || []
165
+ };
166
+ });
167
+ return result;
168
+ }
169
+ function bindAsyncGenerator(ctx, generator) {
170
+ return {
171
+ // Bind the next() method to execute within the provided context
172
+ next: context.bind(ctx, generator.next.bind(generator)),
173
+ // Bind the return() method to execute within the provided context
174
+ return: context.bind(ctx, generator.return.bind(generator)),
175
+ // Bind the throw() method to execute within the provided context
176
+ throw: context.bind(ctx, generator.throw.bind(generator)),
177
+ // Ensure the async iterator symbol also returns a context-bound generator
178
+ [Symbol.asyncIterator]() {
179
+ return bindAsyncGenerator(ctx, generator[Symbol.asyncIterator]());
180
+ }
181
+ };
182
+ }
183
+ function shouldAddRequestResponseToSpans() {
184
+ const envValue = process.env.ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS || "true";
185
+ return envValue === "true" || envValue === "1";
186
+ }
187
+ export {
188
+ bindAsyncGenerator,
189
+ traceAgentInvocation,
190
+ traceCallLlm,
191
+ traceMergedToolCalls,
192
+ traceSendData,
193
+ traceToolCall,
194
+ tracer
195
+ };
@@ -0,0 +1,104 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2025 Google LLC
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { Type } from "@google/genai";
7
+ import { LlmAgent } from "../agents/llm_agent.js";
8
+ import { InMemoryMemoryService } from "../memory/in_memory_memory_service.js";
9
+ import { Runner } from "../runner/runner.js";
10
+ import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
11
+ import { GoogleLLMVariant } from "../utils/variant_utils.js";
12
+ import { BaseTool } from "./base_tool.js";
13
+ import { ForwardingArtifactService } from "./forwarding_artifact_service.js";
14
+ class AgentTool extends BaseTool {
15
+ constructor(config) {
16
+ super(
17
+ { name: config.agent.name, description: config.agent.description || "" }
18
+ );
19
+ this.agent = config.agent;
20
+ this.skipSummarization = config.skipSummarization || false;
21
+ }
22
+ _getDeclaration() {
23
+ let declaration;
24
+ if (this.agent instanceof LlmAgent && this.agent.inputSchema) {
25
+ declaration = {
26
+ name: this.name,
27
+ description: this.description,
28
+ // TODO(b/425992518): We should not use the agent's input schema as is.
29
+ // It should be validated and possibly transformed. Consider similar
30
+ // logic to one we have in Python ADK.
31
+ parameters: this.agent.inputSchema
32
+ };
33
+ } else {
34
+ declaration = {
35
+ name: this.name,
36
+ description: this.description,
37
+ parameters: {
38
+ type: Type.OBJECT,
39
+ properties: {
40
+ "request": {
41
+ type: Type.STRING
42
+ }
43
+ },
44
+ required: ["request"]
45
+ }
46
+ };
47
+ }
48
+ if (this.apiVariant !== GoogleLLMVariant.GEMINI_API) {
49
+ const hasOutputSchema = this.agent instanceof LlmAgent && this.agent.outputSchema;
50
+ declaration.response = hasOutputSchema ? { type: Type.OBJECT } : { type: Type.STRING };
51
+ }
52
+ return declaration;
53
+ }
54
+ async runAsync({ args, toolContext }) {
55
+ var _a, _b;
56
+ if (this.skipSummarization) {
57
+ toolContext.actions.skipSummarization = true;
58
+ }
59
+ const hasInputSchema = this.agent instanceof LlmAgent && this.agent.inputSchema;
60
+ const content = {
61
+ role: "user",
62
+ parts: [
63
+ {
64
+ // TODO(b/425992518): Should be validated. Consider similar
65
+ // logic to one we have in Python ADK.
66
+ text: hasInputSchema ? JSON.stringify(args) : args["request"]
67
+ }
68
+ ]
69
+ };
70
+ const runner = new Runner({
71
+ appName: this.agent.name,
72
+ agent: this.agent,
73
+ artifactService: new ForwardingArtifactService(toolContext),
74
+ sessionService: new InMemorySessionService(),
75
+ memoryService: new InMemoryMemoryService(),
76
+ credentialService: toolContext.invocationContext.credentialService
77
+ });
78
+ const session = await runner.sessionService.createSession({
79
+ appName: this.agent.name,
80
+ userId: "tmp_user",
81
+ state: toolContext.state.toRecord()
82
+ });
83
+ let lastEvent;
84
+ for await (const event of runner.runAsync({
85
+ userId: session.userId,
86
+ sessionId: session.id,
87
+ newMessage: content
88
+ })) {
89
+ if (event.actions.stateDelta) {
90
+ toolContext.state.update(event.actions.stateDelta);
91
+ }
92
+ lastEvent = event;
93
+ }
94
+ if (!((_b = (_a = lastEvent == null ? void 0 : lastEvent.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.length)) {
95
+ return "";
96
+ }
97
+ const hasOutputSchema = this.agent instanceof LlmAgent && this.agent.outputSchema;
98
+ const mergetText = lastEvent.content.parts.map((part) => part.text).filter((text) => text).join("\n");
99
+ return hasOutputSchema ? JSON.parse(mergetText) : mergetText;
100
+ }
101
+ }
102
+ export {
103
+ AgentTool
104
+ };