@simple-ai-lab/sdk 0.4.0 → 0.8.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 (78) hide show
  1. package/README.md +79 -1
  2. package/dist/actions.cjs +452 -0
  3. package/dist/actions.d.cts +348 -0
  4. package/dist/actions.d.ts +348 -0
  5. package/dist/actions.js +443 -0
  6. package/dist/agents.cjs +1176 -0
  7. package/dist/agents.d.cts +1138 -0
  8. package/dist/agents.d.ts +1138 -0
  9. package/dist/agents.js +1166 -0
  10. package/dist/built-in-actions.cjs +456 -0
  11. package/dist/built-in-actions.d.cts +53 -0
  12. package/dist/built-in-actions.d.ts +53 -0
  13. package/dist/built-in-actions.js +453 -0
  14. package/dist/client.cjs +29 -0
  15. package/dist/client.d.cts +15 -0
  16. package/dist/client.d.ts +15 -0
  17. package/dist/client.js +25 -0
  18. package/dist/code-action/defaults.cjs +11 -0
  19. package/dist/code-action/defaults.d.cts +7 -0
  20. package/dist/code-action/defaults.d.ts +7 -0
  21. package/dist/code-action/defaults.js +8 -0
  22. package/dist/code-action/define-action.cjs +78 -0
  23. package/dist/code-action/define-action.d.cts +99 -0
  24. package/dist/code-action/define-action.d.ts +99 -0
  25. package/dist/code-action/define-action.js +73 -0
  26. package/dist/code-action/index.cjs +11 -0
  27. package/dist/code-action/index.d.cts +4 -0
  28. package/dist/code-action/index.d.ts +4 -0
  29. package/dist/code-action/index.js +3 -0
  30. package/dist/code-action/llm.cjs +34 -0
  31. package/dist/code-action/llm.d.cts +28 -0
  32. package/dist/code-action/llm.d.ts +28 -0
  33. package/dist/code-action/llm.js +31 -0
  34. package/dist/code-action/types.cjs +14 -0
  35. package/dist/code-action/types.d.cts +19 -0
  36. package/dist/code-action/types.d.ts +19 -0
  37. package/dist/code-action/types.js +11 -0
  38. package/dist/code-action/workflow.cjs +29 -0
  39. package/dist/code-action/workflow.d.cts +53 -0
  40. package/dist/code-action/workflow.d.ts +53 -0
  41. package/dist/code-action/workflow.js +26 -0
  42. package/dist/data.cjs +98 -0
  43. package/dist/data.d.cts +44 -0
  44. package/dist/data.d.ts +44 -0
  45. package/dist/data.js +94 -0
  46. package/dist/http.cjs +72 -0
  47. package/dist/http.d.cts +14 -0
  48. package/dist/http.d.ts +14 -0
  49. package/dist/http.js +69 -0
  50. package/dist/index.cjs +71 -1597
  51. package/dist/index.d.cts +12 -780
  52. package/dist/index.d.ts +12 -780
  53. package/dist/index.js +10 -1311
  54. package/dist/projects.cjs +234 -0
  55. package/dist/projects.d.cts +24 -0
  56. package/dist/projects.d.ts +24 -0
  57. package/dist/projects.js +228 -0
  58. package/dist/schemas.cjs +50 -0
  59. package/dist/schemas.d.cts +81 -0
  60. package/dist/schemas.d.ts +81 -0
  61. package/dist/schemas.js +47 -0
  62. package/dist/shared/errors.cjs +31 -0
  63. package/dist/shared/errors.d.cts +22 -0
  64. package/dist/shared/errors.d.ts +22 -0
  65. package/dist/shared/errors.js +26 -0
  66. package/package.json +27 -31
  67. package/dist/chunk-V4E5PSKB.js +0 -267
  68. package/dist/chunk-V4E5PSKB.js.map +0 -1
  69. package/dist/code-action-CDt77m7I.d.cts +0 -191
  70. package/dist/code-action-CDt77m7I.d.ts +0 -191
  71. package/dist/code-action.cjs +0 -282
  72. package/dist/code-action.cjs.map +0 -1
  73. package/dist/code-action.d.cts +0 -2
  74. package/dist/code-action.d.ts +0 -2
  75. package/dist/code-action.js +0 -9
  76. package/dist/code-action.js.map +0 -1
  77. package/dist/index.cjs.map +0 -1
  78. package/dist/index.js.map +0 -1
package/README.md CHANGED
@@ -16,12 +16,78 @@ export default defineAction(async ({ inputs, config, client }) => {
16
16
  tableName: 'customers',
17
17
  filters: [{ column: 'email', values: [inputs.email] }],
18
18
  });
19
+
19
20
  return { found: records.length > 0 };
20
21
  });
21
22
  ```
22
23
 
23
24
  No API key handling needed. Simple routes SDK requests through a protected outbound binding that injects a short-lived, organization-scoped credential without exposing it to action code.
24
25
 
26
+ ### Steering the conversation
27
+
28
+ An action invoked from a workflow can send the caller somewhere else. `workflow.transitionTo` records the node to run next, so the agent goes there instead of following the node's own edges. It returns normally: the rest of your handler still runs, and the value you return is still mapped to the action's outputs.
29
+
30
+ ```typescript
31
+ import { defineAction } from '@simple-ai-lab/sdk';
32
+
33
+ export default defineAction(async ({ inputs, client, workflow }) => {
34
+ const { records } = await client.data.query({
35
+ tableName: 'accounts',
36
+ filters: [{ column: 'email', values: [inputs.email] }],
37
+ });
38
+
39
+ if (records[0]?.status === 'delinquent') {
40
+ workflow.transitionTo({
41
+ nodeName: 'Collections',
42
+ message: 'Let me get you to the right team.',
43
+ reason: 'account is delinquent',
44
+ });
45
+ }
46
+
47
+ return { status: records[0]?.status ?? 'unknown' };
48
+ });
49
+ ```
50
+
51
+ A transition accompanies the result rather than replacing it, so the example above both writes `status` to its outputs and moves the conversation. Asking twice keeps the last request, and an action that throws transitions nowhere.
52
+
53
+ The same action can run where there is no conversation to steer — as a per-turn action, an automatic before/after-call action, or in data sync. Those invocations do not grant `WORKFLOW_TRANSITION`, and `transitionTo` throws `MissingCapabilityError` instead. If your action runs in both places, check first:
54
+
55
+ ```typescript
56
+ import { ActionCapability, defineAction } from '@simple-ai-lab/sdk';
57
+
58
+ export default defineAction(async ({ metadata, workflow }) => {
59
+ if (metadata.capabilities.includes(ActionCapability.WORKFLOW_TRANSITION)) {
60
+ workflow.transitionTo({ nodeName: 'Collections' });
61
+ }
62
+ return { escalated: false };
63
+ });
64
+ ```
65
+
66
+ ### Calling an LLM
67
+
68
+ `llm.infer` sends an [OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create) request through Simple AI's LLM router, so the action needs no LLM provider key of its own. `model` is a router ladder slug, not a vendor model ID; ask Simple AI support which slugs to use. Requests are never streamed, and the response comes back with its `output` typed:
69
+
70
+ ```typescript
71
+ import { defineAction } from '@simple-ai-lab/sdk';
72
+
73
+ export default defineAction(async ({ inputs, llm }) => {
74
+ const response = await llm.infer({
75
+ model: '<router ladder slug>',
76
+ instructions: 'Summarize the caller notes in one sentence.',
77
+ input: inputs.notes,
78
+ });
79
+ const summary = response.output
80
+ .flatMap((item) => item.content ?? [])
81
+ .filter((part) => part.type === 'output_text')
82
+ .map((part) => part.text)
83
+ .join('');
84
+
85
+ return { summary };
86
+ });
87
+ ```
88
+
89
+ Router refusals throw `SimpleAIError` with the router's `status`, `code`, and message. LLM calls are available in code actions during conversations, automatic before/after-call actions, data sync, and editor test runs. Authentication is provided automatically.
90
+
25
91
  ## In your own application
26
92
 
27
93
  ```typescript
@@ -40,7 +106,7 @@ const { records, total } = await client.data.query({
40
106
 
41
107
  ## Define an agent
42
108
 
43
- Agent authoring is action-first: integrations are immutable Actions, and Agent commits pin exact Action versions. New source does not create legacy tools or HTTP graph nodes.
109
+ Agents use immutable Actions for integrations, and Agent commits pin exact Action versions. New source does not create legacy tools or HTTP graph nodes.
44
110
 
45
111
  ```typescript
46
112
  import { action, defineAgent, node, prompt } from '@simple-ai-lab/sdk';
@@ -89,6 +155,18 @@ export default defineAgent({
89
155
  });
90
156
  ```
91
157
 
158
+ `action.fromAgent(...)` sets an explicit input description override for that callable.
159
+ Inputs omitted from `inputs` inherit their Action schema descriptions at runtime;
160
+ the SDK leaves those overrides absent in the compiled Agent.
161
+
162
+ Built-in Actions use Agent v2 schemas by default. To preserve a pulled Action
163
+ version's stored schemas, provide `input`, `output`, and `outputMappings` together.
164
+
165
+ `call.backgroundNoise` takes the Agent v2 block, `{ trackName, gainMultiplier }`.
166
+ Leave `gainMultiplier` out to keep it out of the commit, and pass
167
+ `backgroundNoise: null` for an Agent with no background noise configured at all.
168
+ Left unset, the block follows `voice.backgroundNoise` at gain 1.
169
+
92
170
  Install `@simple-ai-lab/cli` for `simple init`, `pull`, `typecheck`, `diff`, and `publish`.
93
171
 
94
172
  ## Documentation
@@ -0,0 +1,452 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.action = void 0;
4
+ exports.resolveActionHttpHeaders = resolveActionHttpHeaders;
5
+ exports.resolveActionIoSchema = resolveActionIoSchema;
6
+ exports.actionsIoSchemaFromZod = actionsIoSchemaFromZod;
7
+ exports.canonicalActionSource = canonicalActionSource;
8
+ exports.compileAction = compileAction;
9
+ exports.sourceFile = sourceFile;
10
+ const zod_1 = require("zod");
11
+ const built_in_actions_1 = require("./built-in-actions.cjs");
12
+ function resolveActionHttpHeaders(headers) {
13
+ if (headers === undefined) {
14
+ return [];
15
+ }
16
+ return Array.isArray(headers)
17
+ ? headers
18
+ : Object.entries(headers).map(([name, valueTemplate]) => ({ name, valueTemplate }));
19
+ }
20
+ function resolveActionIoSchema(schema) {
21
+ if (schema instanceof zod_1.z.ZodType) {
22
+ return actionsIoSchemaFromZod(schema);
23
+ }
24
+ if ('_zod' in schema || '_def' in schema) {
25
+ throw new Error('Action input and output schemas must be Zod 4 objects or JSON Schema objects');
26
+ }
27
+ return schema;
28
+ }
29
+ function isRecord(value) {
30
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
31
+ }
32
+ function nullableJsonSchema(value) {
33
+ const type = value.type;
34
+ if (Array.isArray(type)) {
35
+ const nonNullTypes = type.filter((item) => item !== 'null');
36
+ if (nonNullTypes.length === 1 && typeof nonNullTypes[0] === 'string') {
37
+ return { schema: { ...value, type: nonNullTypes[0] }, nullable: type.includes('null') };
38
+ }
39
+ }
40
+ const anyOf = value.anyOf;
41
+ if (Array.isArray(anyOf)) {
42
+ const schemas = anyOf.filter(isRecord);
43
+ const nonNullSchemas = schemas.filter((schema) => schema.type !== 'null');
44
+ const containsNull = schemas.some((schema) => schema.type === 'null');
45
+ if (containsNull && nonNullSchemas.length === 1) {
46
+ const nonNullSchema = nonNullSchemas[0] ?? {};
47
+ return {
48
+ schema: {
49
+ ...nonNullSchema,
50
+ ...(typeof value.description === 'string' ? { description: value.description } : {}),
51
+ },
52
+ nullable: true,
53
+ };
54
+ }
55
+ }
56
+ return { schema: value, nullable: false };
57
+ }
58
+ function schemaDescription(schema) {
59
+ return typeof schema.description === 'string' ? schema.description : '';
60
+ }
61
+ function convertJsonSchemaNode(value, path) {
62
+ if (!isRecord(value)) {
63
+ throw new Error(`${path} is not a representable Zod schema`);
64
+ }
65
+ const { schema, nullable } = nullableJsonSchema(value);
66
+ if (schema.enum !== undefined || schema.const !== undefined) {
67
+ throw new Error(`${path} uses enum/const, which Actions I/O schemas do not support`);
68
+ }
69
+ switch (schema.type) {
70
+ case 'string':
71
+ case 'number':
72
+ case 'boolean':
73
+ return {
74
+ type: schema.type,
75
+ description: schemaDescription(schema),
76
+ nullable,
77
+ };
78
+ case 'object': {
79
+ const rawProperties = isRecord(schema.properties) ? schema.properties : {};
80
+ const properties = {};
81
+ for (const [name, child] of Object.entries(rawProperties)) {
82
+ if (!/^[A-Za-z_]\w*$/.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name)) {
83
+ throw new Error(`${path}.${name} is not a valid Actions I/O property name`);
84
+ }
85
+ properties[name] = convertJsonSchemaNode(child, `${path}.${name}`);
86
+ }
87
+ const required = Array.isArray(schema.required)
88
+ ? schema.required.filter((name) => typeof name === 'string')
89
+ : [];
90
+ const additionalProperties = schema.additionalProperties === true;
91
+ return {
92
+ type: 'object',
93
+ description: schemaDescription(schema),
94
+ nullable,
95
+ properties,
96
+ required,
97
+ additionalProperties,
98
+ };
99
+ }
100
+ case 'array':
101
+ return {
102
+ type: 'array',
103
+ description: schemaDescription(schema),
104
+ nullable,
105
+ ...(schema.items === undefined ? {} : { items: convertJsonSchemaNode(schema.items, `${path}[]`) }),
106
+ };
107
+ case 'integer':
108
+ return {
109
+ type: 'number',
110
+ description: schemaDescription(schema),
111
+ nullable,
112
+ };
113
+ default:
114
+ throw new Error(`${path} uses unsupported Zod/JSON Schema type "${String(schema.type)}"`);
115
+ }
116
+ }
117
+ function actionsIoSchemaFromZod(schema) {
118
+ const converted = convertJsonSchemaNode(zod_1.z.toJSONSchema(schema), 'schema');
119
+ if (converted.type !== 'object') {
120
+ throw new Error('Action input and output schemas must be Zod objects');
121
+ }
122
+ return {
123
+ type: 'object',
124
+ description: converted.description,
125
+ properties: converted.properties,
126
+ required: converted.required,
127
+ additionalProperties: converted.additionalProperties,
128
+ };
129
+ }
130
+ function pointerForName(name) {
131
+ const escaped = name.replace(/~/g, '~0').replace(/\//g, '~1');
132
+ return `/${escaped}`;
133
+ }
134
+ function normalizeOutputMappings({ mappings, outputSchema, }) {
135
+ const normalized = Object.fromEntries(Object.entries(mappings).map(([name, template]) => [name.startsWith('/') ? name : pointerForName(name), template]));
136
+ for (const name of Object.keys(outputSchema.properties)) {
137
+ const pointer = pointerForName(name);
138
+ if (normalized[pointer] === undefined) {
139
+ throw new Error(`Action output "${name}" needs an output mapping`);
140
+ }
141
+ }
142
+ for (const pointer of Object.keys(normalized)) {
143
+ const firstToken = pointer.slice(1).split('/')[0]?.replace(/~1/g, '/').replace(/~0/g, '~');
144
+ if (firstToken === undefined || outputSchema.properties[firstToken] === undefined) {
145
+ throw new Error(`Action output mapping "${pointer}" does not reference a declared output`);
146
+ }
147
+ }
148
+ return normalized;
149
+ }
150
+ function compileContracts({ input, output }) {
151
+ return {
152
+ inputSchema: resolveActionIoSchema(input),
153
+ outputSchema: resolveActionIoSchema(output),
154
+ };
155
+ }
156
+ /**
157
+ * Code Action source shared by SDK compilation, CLI comparisons, and file hashes.
158
+ * Surrounding whitespace is trimmed to match Agent v2. Line endings use LF for
159
+ * consistent comparisons across operating systems. Publishing writes this form.
160
+ */
161
+ function canonicalActionSource(source) {
162
+ return source.replace(/\r\n?/g, '\n').trim();
163
+ }
164
+ /**
165
+ * Resolves a handler's TypeScript, whether it is written inline or kept in the
166
+ * file a `sourceFile(...)` reference names, in its canonical form.
167
+ */
168
+ function resolveActionSource({ source, options, }) {
169
+ if (typeof source === 'string') {
170
+ return canonicalActionSource(source);
171
+ }
172
+ if (options.readSourceFile === undefined) {
173
+ throw new Error(`Action source file "${source.path}" requires a readSourceFile compiler option`);
174
+ }
175
+ return canonicalActionSource(options.readSourceFile(source.path));
176
+ }
177
+ function compileHttpAction(config) {
178
+ const contract = compileContracts(config);
179
+ return {
180
+ kind: 'inline',
181
+ key: config.key,
182
+ contract,
183
+ compile: () => ({
184
+ actionType: 'http',
185
+ name: config.name,
186
+ description: config.description,
187
+ ...contract,
188
+ outputMappings: normalizeOutputMappings({
189
+ mappings: config.outputMappings,
190
+ outputSchema: contract.outputSchema,
191
+ }),
192
+ operation: {
193
+ type: 'request',
194
+ method: config.request.method,
195
+ urlTemplate: config.request.url,
196
+ headers: resolveActionHttpHeaders(config.request.headers),
197
+ bodyTemplate: config.request.body ?? null,
198
+ },
199
+ }),
200
+ };
201
+ }
202
+ function compileCodeAction(config) {
203
+ const contract = compileContracts(config);
204
+ return {
205
+ kind: 'inline',
206
+ key: config.key,
207
+ contract,
208
+ compile: (options) => ({
209
+ actionType: 'code',
210
+ name: config.name,
211
+ description: config.description,
212
+ ...contract,
213
+ outputMappings: normalizeOutputMappings({
214
+ mappings: config.outputMappings,
215
+ outputSchema: contract.outputSchema,
216
+ }),
217
+ operation: {
218
+ type: 'execute',
219
+ language: 'typescript',
220
+ source: resolveActionSource({ source: config.source, options }),
221
+ compiledJs: null,
222
+ runtime: 'cloudflare-worker',
223
+ timeoutMs: config.timeoutMs ?? 30_000,
224
+ },
225
+ }),
226
+ };
227
+ }
228
+ const CUSTOM_DATA_AGENT_SEARCH_INPUT_SCHEMA = {
229
+ type: 'object',
230
+ description: 'System-managed Custom Data search inputs.',
231
+ properties: {},
232
+ required: [],
233
+ additionalProperties: true,
234
+ };
235
+ function compileCustomDataTransform({ transform, options, }) {
236
+ if (transform == null) {
237
+ return null;
238
+ }
239
+ return {
240
+ language: 'typescript',
241
+ source: resolveActionSource({ source: transform.source, options }),
242
+ compiledJs: null,
243
+ runtime: 'cloudflare-worker',
244
+ timeoutMs: transform.timeoutMs ?? 30_000,
245
+ };
246
+ }
247
+ function compileCustomDataAction(config) {
248
+ const outputSchema = resolveActionIoSchema(config.output);
249
+ let inputSchema;
250
+ switch (config.operation.type) {
251
+ case 'agent_search':
252
+ inputSchema = CUSTOM_DATA_AGENT_SEARCH_INPUT_SCHEMA;
253
+ break;
254
+ case 'query':
255
+ case 'search':
256
+ if (config.input === undefined) {
257
+ throw new Error(`Custom Data ${config.operation.type} Actions require an input schema`);
258
+ }
259
+ inputSchema = resolveActionIoSchema(config.input);
260
+ break;
261
+ }
262
+ const contract = { inputSchema, outputSchema };
263
+ return {
264
+ kind: 'inline',
265
+ key: config.key,
266
+ contract,
267
+ compile: (options) => {
268
+ const transform = compileCustomDataTransform({ transform: config.transform, options });
269
+ const common = {
270
+ actionType: 'custom_data',
271
+ name: config.name,
272
+ description: config.description,
273
+ ...contract,
274
+ outputMappings: normalizeOutputMappings({
275
+ mappings: config.outputMappings,
276
+ outputSchema: contract.outputSchema,
277
+ }),
278
+ };
279
+ switch (config.operation.type) {
280
+ case 'agent_search':
281
+ return {
282
+ ...common,
283
+ operation: {
284
+ ...config.operation,
285
+ aiFacetingEnabled: config.operation.aiFacetingEnabled ?? false,
286
+ transform,
287
+ },
288
+ };
289
+ case 'query':
290
+ return { ...common, operation: { ...config.operation, transform } };
291
+ case 'search': {
292
+ const { body, ...operation } = config.operation;
293
+ return { ...common, operation: { ...operation, bodyTemplate: body, transform } };
294
+ }
295
+ }
296
+ },
297
+ };
298
+ }
299
+ function compileCustomDataQueryAction(config) {
300
+ const { sql, ...common } = config;
301
+ return compileCustomDataAction({ ...common, operation: { type: 'query', sql } });
302
+ }
303
+ function compileCustomDataSearchAction(config) {
304
+ const { table, body, ...common } = config;
305
+ return compileCustomDataAction({ ...common, operation: { type: 'search', table, body } });
306
+ }
307
+ function compileKnowledgeBaseSearchAction(config) {
308
+ const contract = compileContracts(config);
309
+ return {
310
+ kind: 'inline',
311
+ key: config.key,
312
+ contract,
313
+ compile: () => ({
314
+ actionType: 'knowledge_base',
315
+ name: config.name,
316
+ description: config.description,
317
+ ...contract,
318
+ outputMappings: normalizeOutputMappings({
319
+ mappings: config.outputMappings,
320
+ outputSchema: contract.outputSchema,
321
+ }),
322
+ operation: {
323
+ type: 'search',
324
+ knowledgeBaseIds: config.knowledgeBaseIds,
325
+ bodyTemplate: config.body,
326
+ },
327
+ }),
328
+ };
329
+ }
330
+ /** Compiles built-in schema parameters through the same path as other Actions. */
331
+ function compileBuiltInAction({ config, operation, }) {
332
+ // Validate against the Agent v2 operation schema without applying its transforms:
333
+ // historical versions must retain their stored strings when pulled and diffed.
334
+ built_in_actions_1.builtInOperationSchema.parse(operation);
335
+ const { key, name, description } = config;
336
+ if ('contract' in config) {
337
+ throw new Error(`Built-in Action "${key}" no longer accepts contract; use input, output, and outputMappings`);
338
+ }
339
+ // JavaScript callers and CLI compilation do not run TypeScript checks.
340
+ // A partial stored contract must never be mixed with Agent v2 defaults.
341
+ const hasSchemas = config.input !== undefined || config.output !== undefined || config.outputMappings !== undefined;
342
+ if (hasSchemas &&
343
+ (config.input === undefined || config.output === undefined || config.outputMappings === undefined)) {
344
+ throw new Error(`Built-in Action "${key}" requires input, output, and outputMappings together`);
345
+ }
346
+ const fixed = built_in_actions_1.BUILT_IN_ACTION_CONTRACTS[operation.type];
347
+ const schemas = config.input === undefined
348
+ ? { input: fixed.inputSchema, output: fixed.outputSchema, outputMappings: fixed.outputMappings }
349
+ : config;
350
+ const contract = compileContracts(schemas);
351
+ return {
352
+ kind: 'inline',
353
+ key,
354
+ contract,
355
+ compile: () => ({
356
+ actionType: 'built_in',
357
+ name,
358
+ description,
359
+ ...contract,
360
+ outputMappings: normalizeOutputMappings({
361
+ mappings: schemas.outputMappings,
362
+ outputSchema: contract.outputSchema,
363
+ }),
364
+ operation,
365
+ }),
366
+ };
367
+ }
368
+ exports.action = {
369
+ http(config) {
370
+ return compileHttpAction(config);
371
+ },
372
+ code(config) {
373
+ return compileCodeAction(config);
374
+ },
375
+ customData: compileCustomDataAction,
376
+ customDataAgentSearch(config) {
377
+ const { table, aiFacetingEnabled = false, ...common } = config;
378
+ return compileCustomDataAction({
379
+ ...common,
380
+ operation: { type: 'agent_search', table, aiFacetingEnabled },
381
+ });
382
+ },
383
+ customDataQuery(config) {
384
+ return compileCustomDataQueryAction(config);
385
+ },
386
+ customDataSearch(config) {
387
+ return compileCustomDataSearchAction(config);
388
+ },
389
+ knowledgeBaseSearch(config) {
390
+ return compileKnowledgeBaseSearchAction(config);
391
+ },
392
+ /** Sends an email through a verified sending domain of the organization. */
393
+ sendEmail(config) {
394
+ const { sendingDomainUuid, fromLocalPart, fromDisplayName = null } = config;
395
+ return compileBuiltInAction({
396
+ config,
397
+ operation: { type: 'send_email', sendingDomainUuid, fromLocalPart, fromDisplayName },
398
+ });
399
+ },
400
+ /** Sends a text message from one of the organization's phone numbers. */
401
+ sendTextMessage(config) {
402
+ const { senderPhoneNumberUuid } = config;
403
+ return compileBuiltInAction({
404
+ config,
405
+ operation: { type: 'send_text_message', senderPhoneNumberUuid },
406
+ });
407
+ },
408
+ /** Validates and standardizes a postal address. */
409
+ validateAddress(config) {
410
+ return compileBuiltInAction({
411
+ config,
412
+ operation: { type: 'validate_address' },
413
+ });
414
+ },
415
+ /** Searches the web and returns the passages of each page most relevant to the question. */
416
+ webSearch(config) {
417
+ const { allowedDomains = [], blockedDomains = [] } = config;
418
+ return compileBuiltInAction({
419
+ config,
420
+ operation: { type: 'web_search', allowedDomains, blockedDomains },
421
+ });
422
+ },
423
+ ref(config) {
424
+ return {
425
+ kind: 'reference',
426
+ key: config.key,
427
+ versionUuid: config.versionUuid,
428
+ contract: config.contract ?? null,
429
+ };
430
+ },
431
+ callable(config) {
432
+ const { backgroundMessage = null, ...rest } = config;
433
+ return { kind: 'callable', ...rest, backgroundMessage };
434
+ },
435
+ run(config) {
436
+ return { kind: 'run', ...config };
437
+ },
438
+ fromAgent(description) {
439
+ return { source: 'agent', description };
440
+ },
441
+ from(value, description) {
442
+ // The description is kept separately on the wire, so a prefilled input can
443
+ // still carry the text the agent is shown.
444
+ return { source: 'template', value, ...(description === undefined ? {} : { description }) };
445
+ },
446
+ };
447
+ function compileAction(definition, options = {}) {
448
+ return definition.compile(options);
449
+ }
450
+ function sourceFile(path) {
451
+ return { kind: 'source-file', path };
452
+ }