@squidcloud/freshdesk-client 1.0.497 → 1.0.499
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.
- package/dist/connectors/freshdesk/common/src/freshdesk-types.d.ts +1 -28
- package/dist/internal-common/src/ai/system-openai-compatible.d.ts +35 -0
- package/dist/internal-common/src/public-types/ai-agent-integrations.public-types.d.ts +71 -0
- package/dist/internal-common/src/public-types/ai-agent.public-types.d.ts +1609 -0
- package/dist/internal-common/src/public-types/ai-common.public-types.d.ts +303 -0
- package/dist/internal-common/src/public-types/ai-function.public-types.d.ts +114 -0
- package/dist/internal-common/src/public-types/ai-knowledge-base.public-types.d.ts +2379 -0
- package/dist/internal-common/src/public-types/ai-query.public-types.d.ts +266 -0
- package/dist/internal-common/src/public-types/api-client.public-types.d.ts +9 -0
- package/dist/internal-common/src/public-types/api.public-types.d.ts +99 -0
- package/dist/internal-common/src/public-types/backend.public-types.d.ts +61 -0
- package/dist/internal-common/src/public-types/connector.public-types.d.ts +12 -0
- package/dist/internal-common/src/public-types/context.public-types.d.ts +83 -0
- package/dist/internal-common/src/public-types/document.public-types.d.ts +71 -0
- package/dist/internal-common/src/public-types/event.public-types.d.ts +18 -0
- package/dist/internal-common/src/public-types/extraction.public-types.d.ts +405 -0
- package/dist/internal-common/src/public-types/http-status.public-types.d.ts +415 -0
- package/dist/internal-common/src/public-types/integration.public-types.d.ts +65 -0
- package/dist/internal-common/src/public-types/job.public-types.d.ts +101 -0
- package/dist/internal-common/src/public-types/langgraph.public-types.d.ts +57 -0
- package/dist/internal-common/src/public-types/metadata-filter.public-types.d.ts +106 -0
- package/dist/internal-common/src/public-types/query.public-types.d.ts +149 -0
- package/dist/internal-common/src/public-types/scheduler.public-types.d.ts +43 -0
- package/dist/internal-common/src/public-types/schema.public-types.d.ts +88 -0
- package/dist/internal-common/src/public-types/secret.public-types.d.ts +82 -0
- package/dist/internal-common/src/public-types/socket.public-types.d.ts +4 -0
- package/dist/internal-common/src/public-types/source-code.public-types.d.ts +208 -0
- package/dist/internal-common/src/public-types/typescript.public-types.d.ts +20 -0
- package/dist/internal-common/src/public-types-backend/ai-agent.public-context.d.ts +105 -0
- package/dist/internal-common/src/public-types-backend/api-call.public-context.d.ts +30 -0
- package/dist/internal-common/src/public-types-backend/application.public-types.d.ts +94 -0
- package/dist/internal-common/src/public-types-backend/bundle-api.public-types.d.ts +199 -0
- package/dist/internal-common/src/public-types-backend/bundle-data.public-types.d.ts +18 -0
- package/dist/internal-common/src/public-types-backend/distributed-lock.public-context.d.ts +4 -0
- package/dist/internal-common/src/public-types-backend/graphql.public-context.d.ts +7 -0
- package/dist/internal-common/src/public-types-backend/langgraph.public-context.d.ts +20 -0
- package/dist/internal-common/src/public-types-backend/mcp.public-types.d.ts +55 -0
- package/dist/internal-common/src/public-types-backend/metric.public-context.d.ts +12 -0
- package/dist/internal-common/src/public-types-backend/mutation.public-context.d.ts +161 -0
- package/dist/internal-common/src/public-types-backend/native-query.public-context.d.ts +75 -0
- package/dist/internal-common/src/public-types-backend/query.public-context.d.ts +193 -0
- package/dist/internal-common/src/public-types-backend/storage.public-types.d.ts +15 -0
- package/dist/internal-common/src/public-types-backend/topic.public-context.d.ts +17 -0
- package/dist/internal-common/src/types/application.types.d.ts +98 -0
- package/dist/internal-common/src/types/backend-run.types.d.ts +55 -0
- package/dist/internal-common/src/types/bundle-data.types.d.ts +18 -0
- package/dist/internal-common/src/types/connector.types.d.ts +77 -0
- package/dist/internal-common/src/types/integrations/ai.types.d.ts +1 -0
- package/dist/internal-common/src/types/integrations/api.types.d.ts +76 -0
- package/dist/internal-common/src/types/integrations/auth.types.d.ts +1 -0
- package/dist/internal-common/src/types/integrations/database.types.d.ts +44 -0
- package/dist/internal-common/src/types/integrations/observability.types.d.ts +1 -0
- package/dist/internal-common/src/types/integrations/queue-types.d.ts +1 -0
- package/dist/internal-common/src/types/integrations/schemas.d.ts +6 -0
- package/dist/internal-common/src/types/integrations/storage-types.d.ts +22 -0
- package/dist/internal-common/src/types/langgraph.types.d.ts +1 -0
- package/dist/internal-common/src/types/openapi.types.d.ts +1 -0
- package/dist/internal-common/src/types/query.types.d.ts +21 -0
- package/dist/internal-common/src/types/secret.types.d.ts +7 -0
- package/dist/internal-common/src/types/time-units.d.ts +1 -0
- package/dist/internal-common/src/utils/object.d.ts +93 -0
- package/dist/internal-common/src/utils/serialization.d.ts +30 -0
- package/dist/internal-common/src/utils/worker-manager-utils.d.ts +2 -0
- package/package.json +2 -2
|
@@ -0,0 +1,1609 @@
|
|
|
1
|
+
import { JSONSchema } from 'json-schema-typed';
|
|
2
|
+
import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, EmbeddingModelIdSpec, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName, VendorAiChatModelName } from './ai-common.public-types';
|
|
3
|
+
import { AiContextMetadata, AiContextMetadataFilter, AiKnowledgeBaseContextType, AiRagType } from './ai-knowledge-base.public-types';
|
|
4
|
+
import { AiFunctionId, AiFunctionIdWithContext, UserAiChatModelName } from './backend.public-types';
|
|
5
|
+
import { AiAgentId, AiContextId, AiKnowledgeBaseId, AppId, IntegrationId } from './communication.public-types';
|
|
6
|
+
import { DocumentExtractionMethod } from './extraction.public-types';
|
|
7
|
+
import { IntegrationType } from './integration.public-types';
|
|
8
|
+
import { JobId } from './job.public-types';
|
|
9
|
+
import { SecretKey } from './secret.public-types';
|
|
10
|
+
/**
|
|
11
|
+
* @category AI
|
|
12
|
+
*/
|
|
13
|
+
export type AiGenerateImageOptions = GptImageOptions | StableDiffusionCoreOptions | FluxOptions;
|
|
14
|
+
/**
|
|
15
|
+
* @category AI
|
|
16
|
+
*/
|
|
17
|
+
export type OpenAiAudioTranscribeOptions = WhisperTranscribeOptions | Gpt4oTranscribeOptions;
|
|
18
|
+
/**
|
|
19
|
+
* @category AI
|
|
20
|
+
*/
|
|
21
|
+
export type AiAudioTranscribeOptions = OpenAiAudioTranscribeOptions;
|
|
22
|
+
/**
|
|
23
|
+
* @category AI
|
|
24
|
+
*/
|
|
25
|
+
export type AiAudioCreateSpeechOptions = OpenAiCreateSpeechOptions;
|
|
26
|
+
/**
|
|
27
|
+
* Base options for generating images with an AI model.
|
|
28
|
+
* @category AI
|
|
29
|
+
*/
|
|
30
|
+
export interface BaseAiGenerateImageOptions {
|
|
31
|
+
/** The name of the AI model to use for image generation. */
|
|
32
|
+
modelName: AiImageModelName;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Base options for transcribing audio with an AI model.
|
|
36
|
+
* @category AI
|
|
37
|
+
*/
|
|
38
|
+
export interface BaseAiAudioTranscribeOptions {
|
|
39
|
+
/** The name of the AI model to use for audio transcription. */
|
|
40
|
+
modelName: AiAudioTranscriptionModelName;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Base options for creating speech with an AI model.
|
|
44
|
+
* @category AI
|
|
45
|
+
*/
|
|
46
|
+
export interface BaseAiAudioCreateSpeechOptions {
|
|
47
|
+
/** The name of the AI model to use for speech creation. */
|
|
48
|
+
modelName: AiAudioCreateSpeechModelName;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Options for generating images using OpenAI's gpt-image-* family of models.
|
|
52
|
+
* @category AI
|
|
53
|
+
*/
|
|
54
|
+
export interface GptImageOptions extends BaseAiGenerateImageOptions {
|
|
55
|
+
/** Specifies the OpenAI image model to use. */
|
|
56
|
+
modelName: OpenAiImageModelName;
|
|
57
|
+
/** The quality of the generated image; defaults to 'auto'. */
|
|
58
|
+
quality?: 'auto' | 'high' | 'medium' | 'low';
|
|
59
|
+
/** The size of the generated image; defaults to '1024x1024'. */
|
|
60
|
+
size?: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
|
|
61
|
+
/** The number of images to generate; defaults to 1. */
|
|
62
|
+
numberOfImagesToGenerate?: number;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Base options shared by all OpenAI audio transcription models.
|
|
66
|
+
* @category AI
|
|
67
|
+
*/
|
|
68
|
+
export interface BaseOpenAiAudioTranscribeOptions extends BaseAiAudioTranscribeOptions {
|
|
69
|
+
/** Specifies the model for audio transcription. */
|
|
70
|
+
modelName: OpenAiAudioTranscriptionModelName;
|
|
71
|
+
/** The temperature for sampling during transcription; defaults to model-specific value. */
|
|
72
|
+
temperature?: number;
|
|
73
|
+
/** An optional prompt to guide the transcription process. */
|
|
74
|
+
prompt?: string;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Options for transcribing audio using the Whisper model.
|
|
78
|
+
* @category AI
|
|
79
|
+
*/
|
|
80
|
+
export interface WhisperTranscribeOptions extends BaseOpenAiAudioTranscribeOptions {
|
|
81
|
+
/** Specifies the Whisper-1 model for audio transcription. */
|
|
82
|
+
modelName: 'whisper-1';
|
|
83
|
+
/** The format of the transcription response; defaults to 'json'. */
|
|
84
|
+
responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Options for transcribing audio using the GPT-4o model.
|
|
88
|
+
* @category AI
|
|
89
|
+
*/
|
|
90
|
+
export interface Gpt4oTranscribeOptions extends BaseOpenAiAudioTranscribeOptions {
|
|
91
|
+
/** Specifies the Whisper-1 model for audio transcription. */
|
|
92
|
+
modelName: 'gpt-4o-transcribe' | 'gpt-4o-mini-transcribe';
|
|
93
|
+
/** The format of the transcription response; defaults to 'json'. */
|
|
94
|
+
responseFormat?: 'json';
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Options for creating speech using OpenAI's text-to-speech models.
|
|
98
|
+
* @category AI
|
|
99
|
+
*/
|
|
100
|
+
export interface OpenAiCreateSpeechOptions extends BaseAiAudioCreateSpeechOptions {
|
|
101
|
+
/** The OpenAI model to use for speech creation (e.g., 'tts-1' or 'tts-1-hd'). */
|
|
102
|
+
modelName: OpenAiAudioCreateSpeechModelName;
|
|
103
|
+
/** The voice to use for speech synthesis; defaults to model-specific value. */
|
|
104
|
+
voice?: 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'fable' | 'onyx' | 'nova' | 'sage' | 'shimmer' | 'verse';
|
|
105
|
+
/** The format of the audio output; defaults to 'mp3'. */
|
|
106
|
+
responseFormat?: OpenAiCreateSpeechFormat;
|
|
107
|
+
/** An optional prompt to guide the speech synthesis process. */
|
|
108
|
+
instructions?: string;
|
|
109
|
+
/** The speed of the speech; defaults to 1.0. */
|
|
110
|
+
speed?: number;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Options for generating images using the Flux model.
|
|
114
|
+
* @category AI
|
|
115
|
+
*/
|
|
116
|
+
export interface FluxOptions extends BaseAiGenerateImageOptions {
|
|
117
|
+
/** Specifies the Flux Pro 1.1 model for image generation. */
|
|
118
|
+
modelName: 'flux-pro-1.1' | 'flux-kontext-pro';
|
|
119
|
+
/** The width of the generated image, must be a multiple of 32, min 256, max 1440; defaults to 1024. */
|
|
120
|
+
width?: number;
|
|
121
|
+
/** The height of the generated image, must be a multiple of 32, min 256, max 1440; defaults to 768. */
|
|
122
|
+
height?: number;
|
|
123
|
+
/** Whether to enhance the prompt for more creative output; defaults to false. */
|
|
124
|
+
prompt_upsampling?: boolean;
|
|
125
|
+
/** A random seed for reproducible generation, if specified. */
|
|
126
|
+
seed?: number;
|
|
127
|
+
/** The safety tolerance level, from 1 (strict) to 5 (permissive). */
|
|
128
|
+
safety_tolerance?: number;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Options for generating images using the Stable Diffusion Core model.
|
|
132
|
+
* @category AI
|
|
133
|
+
*/
|
|
134
|
+
export interface StableDiffusionCoreOptions extends BaseAiGenerateImageOptions {
|
|
135
|
+
/** Specifies the Stable Diffusion Core model for image generation. */
|
|
136
|
+
modelName: 'stable-diffusion-core';
|
|
137
|
+
/** The aspect ratio of the generated image; defaults to '1:1'. */
|
|
138
|
+
aspectRatio?: '16:9' | '1:1' | '21:9' | '2:3' | '3:2' | '4:5' | '5:4' | '9:16' | '9:21';
|
|
139
|
+
/** An optional negative prompt to guide what to exclude from the image. */
|
|
140
|
+
negativePrompt?: string;
|
|
141
|
+
/** A random seed for reproducible generation, if specified. */
|
|
142
|
+
seed?: number;
|
|
143
|
+
/** A style preset to apply to the generated image, if specified. */
|
|
144
|
+
stylePreset?: 'analog-film' | 'anime' | 'cinematic' | 'comic-book' | 'digital-art' | 'enhance' | 'fantasy-art' | 'isometric' | 'line-art' | 'low-poly' | 'modeling-compound' | 'neon-punk' | 'origami' | 'photographic' | 'pixel-art' | 'tile-texture';
|
|
145
|
+
/** The format of the output image; defaults to 'png'. */
|
|
146
|
+
outputFormat?: 'jpeg' | 'png' | 'webp';
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* The possible sources for the LLM provider API key.
|
|
150
|
+
* @category AI
|
|
151
|
+
*/
|
|
152
|
+
export type ApiKeySource = 'user' | 'system';
|
|
153
|
+
/**
|
|
154
|
+
* Structured output format configuration for AI models that support schema-constrained responses.
|
|
155
|
+
*
|
|
156
|
+
* The schema is sent to the model's provider, which constrains decoding to it - the model cannot
|
|
157
|
+
* generate tokens that violate the schema, so the response conforms to it exactly.
|
|
158
|
+
*
|
|
159
|
+
* A schema the provider rejects is reported as a `400` carrying its diagnostic, and a model whose
|
|
160
|
+
* protocol cannot carry a schema at all refuses the request with `STRUCTURED_OUTPUT_NOT_SUPPORTED`
|
|
161
|
+
* rather than answering without the shape that was asked for.
|
|
162
|
+
* **Example:**
|
|
163
|
+
* ```typescript
|
|
164
|
+
* {
|
|
165
|
+
* type: 'json_schema',
|
|
166
|
+
* schema: {
|
|
167
|
+
* type: 'object',
|
|
168
|
+
* properties: {
|
|
169
|
+
* name: { type: 'string' },
|
|
170
|
+
* age: { type: 'number' }
|
|
171
|
+
* },
|
|
172
|
+
* required: ['name', 'age'],
|
|
173
|
+
* additionalProperties: false
|
|
174
|
+
* }
|
|
175
|
+
* }
|
|
176
|
+
* ```
|
|
177
|
+
*
|
|
178
|
+
* @see https://docs.anthropic.com/en/docs/build-with-claude/structured-outputs
|
|
179
|
+
* @see https://platform.openai.com/docs/guides/structured-outputs
|
|
180
|
+
* @see https://ai.google.dev/gemini-api/docs/structured-output
|
|
181
|
+
* @see https://docs.x.ai/docs/guides/structured-outputs
|
|
182
|
+
* @category AI
|
|
183
|
+
*/
|
|
184
|
+
export interface AiStructuredOutputFormat {
|
|
185
|
+
/** The type of structured output. 'json_schema' is the only one. */
|
|
186
|
+
type: 'json_schema';
|
|
187
|
+
/**
|
|
188
|
+
* The JSON schema that the AI response must strictly conform to.
|
|
189
|
+
* Uses constrained decoding to guarantee schema compliance.
|
|
190
|
+
*/
|
|
191
|
+
schema: JSONSchema;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Response format for AI agent responses.
|
|
195
|
+
*
|
|
196
|
+
* **Available formats:**
|
|
197
|
+
* - `'text'`: Plain text response (default) - standard conversational output
|
|
198
|
+
* - `'json_object'`: JSON response - model attempts to return valid JSON, but without strict schema validation
|
|
199
|
+
* - `AiStructuredOutputFormat`: Structured output with schema - guarantees JSON conforms exactly to provided schema
|
|
200
|
+
*
|
|
201
|
+
* **Structured outputs:**
|
|
202
|
+
* Pass an object with `type: 'json_schema'` and a JSON schema. The schema travels to the model's
|
|
203
|
+
* provider, which constrains decoding to it, so the response matches the schema perfectly and
|
|
204
|
+
* parsing or validating it again is unnecessary. A schema the provider rejects comes back as a
|
|
205
|
+
* `400` carrying its diagnostic.
|
|
206
|
+
*
|
|
207
|
+
* Every vendor model carries a schema. The exception is a model whose protocol has no field for
|
|
208
|
+
* one — the CLI agents (`claude-code`, `codex`) and models a customer serves through
|
|
209
|
+
* `@llmService` — where such a request is refused with `STRUCTURED_OUTPUT_NOT_SUPPORTED` rather
|
|
210
|
+
* than answered without the shape it asked for. Use `'json_object'` and state the shape in the
|
|
211
|
+
* prompt for those.
|
|
212
|
+
*
|
|
213
|
+
* **Example with structured output:**
|
|
214
|
+
* ```typescript
|
|
215
|
+
* {
|
|
216
|
+
* responseFormat: {
|
|
217
|
+
* type: 'json_schema',
|
|
218
|
+
* schema: {
|
|
219
|
+
* type: 'object',
|
|
220
|
+
* properties: {
|
|
221
|
+
* sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
|
|
222
|
+
* confidence: { type: 'number', minimum: 0, maximum: 1 }
|
|
223
|
+
* },
|
|
224
|
+
* required: ['sentiment', 'confidence']
|
|
225
|
+
* }
|
|
226
|
+
* }
|
|
227
|
+
* }
|
|
228
|
+
* ```
|
|
229
|
+
*
|
|
230
|
+
* @category AI
|
|
231
|
+
*/
|
|
232
|
+
export type AiAgentResponseFormat = 'text' | 'json_object' | AiStructuredOutputFormat;
|
|
233
|
+
/**
|
|
234
|
+
* @category AI
|
|
235
|
+
*/
|
|
236
|
+
export type AiFileUrlType = 'image' | 'document';
|
|
237
|
+
/**
|
|
238
|
+
* Represents a URL reference to an AI-processed file, such as an image.
|
|
239
|
+
* @category AI
|
|
240
|
+
*/
|
|
241
|
+
export interface AiFileUrl {
|
|
242
|
+
/** The unique identifier for the file URL for the current request. */
|
|
243
|
+
id: string;
|
|
244
|
+
/** The type of file referenced by the URL (e.g., 'image'). */
|
|
245
|
+
type: AiFileUrlType;
|
|
246
|
+
/** The purpose of the file, indicating how it will be used in AI processing. */
|
|
247
|
+
purpose: AiFilePurpose;
|
|
248
|
+
/** The URL pointing to the file. */
|
|
249
|
+
url: string;
|
|
250
|
+
/** An optional description of the file's content or purpose - sent to the AI. */
|
|
251
|
+
description?: string;
|
|
252
|
+
/** The file name, can be used in the prompt to reference the file. */
|
|
253
|
+
fileName?: string;
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* The purpose of the AI file, used to determine how the file should be processed or utilized.
|
|
257
|
+
*
|
|
258
|
+
* - `'context'` - The file is included directly in the AI prompt as contextual content (e.g., images, PDFs).
|
|
259
|
+
* Use this for files that the AI should reference when generating a response.
|
|
260
|
+
* - `'tools'` - The file is returned as part of a tool/function call result (e.g., query results, generated documents).
|
|
261
|
+
* Use this for files produced by AI tools or integrations that should be delivered to the caller alongside the response.
|
|
262
|
+
*/
|
|
263
|
+
export type AiFilePurpose = 'context' | 'tools';
|
|
264
|
+
/**
|
|
265
|
+
* Metadata for an AI agent connected to an integration.
|
|
266
|
+
* @category AI
|
|
267
|
+
*/
|
|
268
|
+
export interface AiConnectedIntegrationMetadata<AiConnectedIntegrationOptionsType = unknown> {
|
|
269
|
+
/** The ID of the connected integration. */
|
|
270
|
+
integrationId: IntegrationId;
|
|
271
|
+
/** The type of the connected integration (e.g., API, database). */
|
|
272
|
+
integrationType: IntegrationType;
|
|
273
|
+
/** An optional description of the integration for the parent agent context, used as AI function description. */
|
|
274
|
+
description?: string;
|
|
275
|
+
/** Optional instructions for the connected integration agent, overriding the default if provided. */
|
|
276
|
+
instructions?: string;
|
|
277
|
+
/**
|
|
278
|
+
* A list of AI function IDs that the AI agent can use from this integration.
|
|
279
|
+
*
|
|
280
|
+
* - When `undefined` (not provided), the AI agent has access to all AI functions for this integration type.
|
|
281
|
+
* - When an empty array `[]`, the AI agent has access to no AI functions.
|
|
282
|
+
* - When an array with function IDs, the AI agent only has access to those specific functions.
|
|
283
|
+
*
|
|
284
|
+
* Example function IDs: 'jiraService__searchJiraIssues', 'confluenceService__searchInConfluence'
|
|
285
|
+
*/
|
|
286
|
+
functionsToUse?: AiFunctionId[];
|
|
287
|
+
/**
|
|
288
|
+
* Additional options for the connected integration.
|
|
289
|
+
* Squid Core or AI functions in connector packages may use these options to adjust behavior of the integration agent.
|
|
290
|
+
*/
|
|
291
|
+
options?: AiConnectedIntegrationOptionsType;
|
|
292
|
+
/**
|
|
293
|
+
* Indicates that this integration should be treated as an MCP server.
|
|
294
|
+
* When true, API integrations with exposeAsMcpServer will be handled through the MCP protocol.
|
|
295
|
+
*/
|
|
296
|
+
connectedAsMcp?: boolean;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* Metadata for a connected AI agent callable by the current agent.
|
|
300
|
+
* @category AI
|
|
301
|
+
*/
|
|
302
|
+
export interface AiConnectedAgentMetadata {
|
|
303
|
+
/** The ID of the connected AI agent. */
|
|
304
|
+
agentId: AiAgentId;
|
|
305
|
+
/** A description of the connected agent for the parent agent context, used as AI function description. */
|
|
306
|
+
description: string;
|
|
307
|
+
}
|
|
308
|
+
/**
|
|
309
|
+
* Metadata for a connected AI Knowledge Base callable by the current agent.
|
|
310
|
+
* @category AI
|
|
311
|
+
*/
|
|
312
|
+
export interface AiConnectedKnowledgeBaseMetadata {
|
|
313
|
+
/** The ID of the connected AI KnowledgeBase */
|
|
314
|
+
knowledgeBaseId: AiKnowledgeBaseId;
|
|
315
|
+
/** A description of when to use this AiKnowledgeBase */
|
|
316
|
+
description: string;
|
|
317
|
+
/**
|
|
318
|
+
* Whether to include document metadata when providing this KB's results to the agent — both chunk
|
|
319
|
+
* search results and literal-scan matches. Defaults to false.
|
|
320
|
+
*/
|
|
321
|
+
includeMetadata?: boolean;
|
|
322
|
+
/**
|
|
323
|
+
* When true, the chat agent gets a tool to enumerate/search this KB's metadata field values on
|
|
324
|
+
* demand. Off by default. (Chat surface only for now; MCP/CLI is not wired.)
|
|
325
|
+
*/
|
|
326
|
+
enableMetadataInspection?: boolean;
|
|
327
|
+
}
|
|
328
|
+
/**
|
|
329
|
+
* Quotas for a single AI chat prompt (`ask()` method call).
|
|
330
|
+
* @category AI
|
|
331
|
+
*/
|
|
332
|
+
export interface AiChatPromptQuotas {
|
|
333
|
+
/**
|
|
334
|
+
* Maximum depth of AI call recursion allowed.
|
|
335
|
+
* Recursion occurs when one AI agent calls another.
|
|
336
|
+
* Note that, for simplicity of implementation, this option guarantees only the maximum recursion depth,
|
|
337
|
+
* not the total number of nested AI calls.
|
|
338
|
+
* Default: 5.
|
|
339
|
+
*/
|
|
340
|
+
maxAiCallStackSize: number;
|
|
341
|
+
/**
|
|
342
|
+
* Maximum wall-clock runtime, in seconds, of a single prompt for CLI-agent models
|
|
343
|
+
* (Claude Code, Codex). Optional override of the per-call self-kill deadline — mainly to
|
|
344
|
+
* tighten it for stricter runaway protection — clamped to [30, 1800]. Ignored for
|
|
345
|
+
* non-CLI-agent models. Default: the platform maximum (30 minutes).
|
|
346
|
+
*/
|
|
347
|
+
maxRuntimeSeconds?: number;
|
|
348
|
+
}
|
|
349
|
+
/**
|
|
350
|
+
* Options for AI agent execution plan, allowing the agent to plan what functionality to use (connected agents,
|
|
351
|
+
* connected, integrations, or functions).
|
|
352
|
+
*/
|
|
353
|
+
export interface AiAgentExecutionPlanOptions {
|
|
354
|
+
/** Whether to enable an execution plan for the agent. */
|
|
355
|
+
enabled: boolean;
|
|
356
|
+
/** The model to use for the execution plan - defaults to the model used by the agent. */
|
|
357
|
+
model?: AiChatModelSelection;
|
|
358
|
+
/** In case the model supports reasoning, this will control the level of effort - defaults to `high`. */
|
|
359
|
+
reasoningEffort?: AiReasoningEffort;
|
|
360
|
+
/**
|
|
361
|
+
* Whether the agent is allowed to ask follow-up or clarification questions.
|
|
362
|
+
* If true, the agent can respond with questions to gather more information before completing the task.
|
|
363
|
+
* Defaults to false.
|
|
364
|
+
*/
|
|
365
|
+
allowClarificationQuestions?: boolean;
|
|
366
|
+
}
|
|
367
|
+
/**
|
|
368
|
+
* The memory mode for an AI agent:
|
|
369
|
+
* - 'none': No memory is used, the agent does not remember past interactions.
|
|
370
|
+
* - 'read-only': The agent can read from memory but cannot write to it.
|
|
371
|
+
* - 'read-write': The agent can both read from and write to memory.
|
|
372
|
+
* @category AI
|
|
373
|
+
*/
|
|
374
|
+
export type AiAgentMemoryMode = 'none' | 'read-only' | 'read-write';
|
|
375
|
+
/**
|
|
376
|
+
* Options for AI agent memory management.
|
|
377
|
+
* @category AI
|
|
378
|
+
*/
|
|
379
|
+
export interface AiAgentMemoryOptions {
|
|
380
|
+
/**
|
|
381
|
+
* The memory mode for an AI agent.
|
|
382
|
+
*
|
|
383
|
+
* Note: Squid persists chat history in its own store only for models whose provider does NOT manage memory
|
|
384
|
+
* itself. For provider-managed-memory models (e.g. Claude Code, which keeps its own CLI session), this mode
|
|
385
|
+
* still controls whether the conversation resumes, but Squid never reads or writes its own history DB.
|
|
386
|
+
*/
|
|
387
|
+
memoryMode: AiAgentMemoryMode;
|
|
388
|
+
/**
|
|
389
|
+
* A unique ID to store the chat memory.
|
|
390
|
+
*
|
|
391
|
+
* The full chat memory key is constructed as a combination of 'appId', 'agentId', and 'memoryId'.
|
|
392
|
+
* If not provided the Squid client instance ID used as a memoryId.
|
|
393
|
+
*
|
|
394
|
+
* Important: the memory ID should be treated with the same security measures as Access Token because it unblocks
|
|
395
|
+
* direct access to the agent chat history. A good practice is to use a non-trivial and a unique value.
|
|
396
|
+
*/
|
|
397
|
+
memoryId?: string;
|
|
398
|
+
/**
|
|
399
|
+
* Overrides the expiration for the whole chat history.
|
|
400
|
+
* If not provided, the expiration will not be changed.
|
|
401
|
+
*
|
|
402
|
+
* Default: the last provided expiration by user or 1 day if
|
|
403
|
+
* the user didn't provide any expiration.
|
|
404
|
+
*/
|
|
405
|
+
expirationMinutes?: number;
|
|
406
|
+
}
|
|
407
|
+
/**
|
|
408
|
+
* Model specification for integration-based LLM providers like Ollama.
|
|
409
|
+
* @category AI
|
|
410
|
+
*/
|
|
411
|
+
export interface IntegrationModelSpec {
|
|
412
|
+
/** The integration ID that provides the LLM */
|
|
413
|
+
integrationId: IntegrationId;
|
|
414
|
+
/** The model name within that integration */
|
|
415
|
+
model: string;
|
|
416
|
+
}
|
|
417
|
+
/**
|
|
418
|
+
* Type for specifying which LLM model to use.
|
|
419
|
+
* Can be either a vendor model name (string) or an integration-based model (object).
|
|
420
|
+
* @category AI
|
|
421
|
+
*/
|
|
422
|
+
export type AiChatModelSelection = AiChatModelName | IntegrationModelSpec;
|
|
423
|
+
/**
|
|
424
|
+
* Lets a routing model pick which of several vendor models answers an `ask` or `chat` request. The routing model
|
|
425
|
+
* sees the question, the agent's instructions and a card per candidate (price, tier, reasoning,
|
|
426
|
+
* context window) and names the one that should answer; that model then serves the request.
|
|
427
|
+
* @category AI
|
|
428
|
+
*/
|
|
429
|
+
export interface AiModelRoutingOptions {
|
|
430
|
+
/** The vendor models the routing model chooses from; at least two, no duplicates. */
|
|
431
|
+
models: VendorAiChatModelName[];
|
|
432
|
+
/** The vendor model that makes the choice. */
|
|
433
|
+
routingModel: VendorAiChatModelName;
|
|
434
|
+
}
|
|
435
|
+
/**
|
|
436
|
+
* The model of an `ask` or `chat` request: a concrete model, or a set of models a routing model chooses from.
|
|
437
|
+
* @category AI
|
|
438
|
+
*/
|
|
439
|
+
export type AiAskModelSelection = AiChatModelSelection | AiModelRoutingOptions;
|
|
440
|
+
/**
|
|
441
|
+
* What a `chat` job resolves to once its stream has ended; read it with `squid.jobs().awaitJob(jobId)`.
|
|
442
|
+
* @category AI
|
|
443
|
+
*/
|
|
444
|
+
export interface AiChatJobResult {
|
|
445
|
+
/** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
|
|
446
|
+
routing?: AiModelRoutingResult;
|
|
447
|
+
}
|
|
448
|
+
/**
|
|
449
|
+
* Chat options as a request carries them: the model may also be a routing choice between several models.
|
|
450
|
+
* @category AI
|
|
451
|
+
*/
|
|
452
|
+
export type AiChatRequestOptions = Omit<AllAiAgentChatOptions, 'model'> & {
|
|
453
|
+
model?: AiAskModelSelection;
|
|
454
|
+
};
|
|
455
|
+
/**
|
|
456
|
+
* How a request whose `model` was an {@link AiModelRoutingOptions} was routed.
|
|
457
|
+
* @category AI
|
|
458
|
+
*/
|
|
459
|
+
export interface AiModelRoutingResult {
|
|
460
|
+
/** The model the routing model chose and the request was sent to. A `backupModel` may still have served it. */
|
|
461
|
+
model: VendorAiChatModelName;
|
|
462
|
+
/** The model that made the choice. */
|
|
463
|
+
routingModel: VendorAiChatModelName;
|
|
464
|
+
/** Input tokens the routing call consumed. */
|
|
465
|
+
inputTokens: number;
|
|
466
|
+
/** Output tokens the routing call generated. */
|
|
467
|
+
outputTokens: number;
|
|
468
|
+
/** Best-effort USD cost of the routing call; undefined when the routing model is unpriced. */
|
|
469
|
+
costUsd?: number;
|
|
470
|
+
}
|
|
471
|
+
/**
|
|
472
|
+
* A backup model together with the sampling settings to run it with. Use this form instead of a
|
|
473
|
+
* bare {@link AiChatModelSelection} when the backup needs settings of its own; anything left unset
|
|
474
|
+
* takes the backup model's own default rather than the primary model's value.
|
|
475
|
+
* @category AI
|
|
476
|
+
*/
|
|
477
|
+
export interface BackupModelOptions {
|
|
478
|
+
/** The model to fall back to. */
|
|
479
|
+
model: AiChatModelSelection;
|
|
480
|
+
/** The temperature to use when sampling from the backup model. */
|
|
481
|
+
temperature?: number;
|
|
482
|
+
/** The level of reasoning effort to apply; effective only for models with reasoning. */
|
|
483
|
+
reasoningEffort?: AiReasoningEffort;
|
|
484
|
+
/** The maximum number of input tokens Squid may send to the backup model. */
|
|
485
|
+
maxTokens?: number;
|
|
486
|
+
/** The maximum number of tokens the backup model should output. */
|
|
487
|
+
maxOutputTokens?: number;
|
|
488
|
+
/** Response length and detail level; supported by OpenAI models only. */
|
|
489
|
+
verbosity?: AiVerbosityLevel;
|
|
490
|
+
}
|
|
491
|
+
/**
|
|
492
|
+
* The base AI agent chat options, should not be used directly.
|
|
493
|
+
* @category AI
|
|
494
|
+
*/
|
|
495
|
+
export interface BaseAiChatOptions {
|
|
496
|
+
/**
|
|
497
|
+
* The maximum number of input tokens that Squid can use when making the request to the AI model.
|
|
498
|
+
* Defaults to the max tokens the model can accept.
|
|
499
|
+
*/
|
|
500
|
+
maxTokens?: number;
|
|
501
|
+
/**
|
|
502
|
+
* The maximum number of tokens the model should output.
|
|
503
|
+
* Passed directly to the AI model. Can be used to control the output verbosity.
|
|
504
|
+
*/
|
|
505
|
+
maxOutputTokens?: number;
|
|
506
|
+
/** The context ID to use for the request. If not provided, the agent's default context will be used. */
|
|
507
|
+
memoryOptions?: AiAgentMemoryOptions;
|
|
508
|
+
/**
|
|
509
|
+
* Names a persistent working directory for CLI-backed agents (`claude-code`, `codex`). When set, the
|
|
510
|
+
* agent runs in a directory keyed by this id, synced across pod replicas via the shared workspace
|
|
511
|
+
* server, so files created in one ask persist and are visible to later asks reusing the same id —
|
|
512
|
+
* including across providers.
|
|
513
|
+
*
|
|
514
|
+
* Pass the same id consistently for a conversation; changing it points the agent at a different
|
|
515
|
+
* directory (and, for Claude Code, starts a fresh transcript). Must match `[A-Za-z0-9_-]` (1-200 chars).
|
|
516
|
+
* Ignored by non-CLI agents and when the workspace server is unconfigured (falls back to a pod-local,
|
|
517
|
+
* non-synced, ephemeral dir).
|
|
518
|
+
*/
|
|
519
|
+
workspaceId?: string;
|
|
520
|
+
/** Whether to disable the whole context for the request. Default to false. */
|
|
521
|
+
disableContext?: boolean;
|
|
522
|
+
/**
|
|
523
|
+
* Whether to use the legacy knowledge base context mode, where KB results are fetched upfront
|
|
524
|
+
* and appended directly to the prompt. When false (default), the KB is exposed as a callable
|
|
525
|
+
* tool that the LLM can invoke on demand.
|
|
526
|
+
*/
|
|
527
|
+
legacyKnowledgeBaseContext?: boolean;
|
|
528
|
+
/** Rewrite prompt for RAG - defaults to false */
|
|
529
|
+
enablePromptRewriteForRag?: boolean;
|
|
530
|
+
/**
|
|
531
|
+
* Whether to include references from the source context in the response. Default to false.
|
|
532
|
+
* @deprecated Use citation instead. Kept for compatibility; renders the legacy Quote/Source format
|
|
533
|
+
* on the legacy upfront-RAG path only.
|
|
534
|
+
*/
|
|
535
|
+
includeReference?: boolean;
|
|
536
|
+
/**
|
|
537
|
+
* When true, the agent cites the sources behind its statements: source name, plus a download link
|
|
538
|
+
* when the agent's stored options set `allowSourceDownloads`. Takes precedence over the deprecated
|
|
539
|
+
* `includeReference`. Default to false.
|
|
540
|
+
*/
|
|
541
|
+
citation?: boolean;
|
|
542
|
+
/**
|
|
543
|
+
* Allows citation links to the original source files (presigned, 1h expiry). Honored ONLY from the
|
|
544
|
+
* agent's stored options — the per-request value is ignored, so callers of public agents can never
|
|
545
|
+
* enable downloads. Default to false (citations render source names only).
|
|
546
|
+
*/
|
|
547
|
+
allowSourceDownloads?: boolean;
|
|
548
|
+
/**
|
|
549
|
+
* The format of the response from the AI model. Defaults to 'text'. A `json_schema` format is
|
|
550
|
+
* refused for a model whose provider has no way to carry a schema — see
|
|
551
|
+
* {@link AiAgentResponseFormat}.
|
|
552
|
+
*/
|
|
553
|
+
responseFormat?: AiAgentResponseFormat;
|
|
554
|
+
/** Whether to response in a "smooth typing" way, beneficial when the chat result is displayed in a UI. Default to true. */
|
|
555
|
+
smoothTyping?: boolean;
|
|
556
|
+
/**
|
|
557
|
+
* Global context passed to the agent and all AI functions of the agent. A request's value also reaches the AI
|
|
558
|
+
* functions of its connected agents, merged over each one's stored `agentContext`. Its keys are caller input and
|
|
559
|
+
* win over stored ones: only the root agent's `@secureAiAgent` rules can vet them, and none run for a public agent.
|
|
560
|
+
*/
|
|
561
|
+
agentContext?: Record<string, unknown>;
|
|
562
|
+
/**
|
|
563
|
+
* Functions to expose to the AI.
|
|
564
|
+
* Either a function name or a name with an extra function context passed only to this function.
|
|
565
|
+
* The parameter values must be valid serializable JSON values.
|
|
566
|
+
* Overrides the stored value.
|
|
567
|
+
*/
|
|
568
|
+
functions?: Array<AiFunctionId | AiFunctionIdWithContext>;
|
|
569
|
+
/** Instructions to include with the prompt. */
|
|
570
|
+
instructions?: string;
|
|
571
|
+
/** A set of filters that will limit the context the AI can access.
|
|
572
|
+
* @deprecated use `contextMetadataFilterForKnowledgeBase` instead.
|
|
573
|
+
*/
|
|
574
|
+
contextMetadataFilter?: AiContextMetadataFilter;
|
|
575
|
+
/** A set of filters that will limit the context the AI can access. */
|
|
576
|
+
contextMetadataFilterForKnowledgeBase?: Record<AiKnowledgeBaseId, AiContextMetadataFilter>;
|
|
577
|
+
/** The options to use for the response in voice. */
|
|
578
|
+
voiceOptions?: AiAudioCreateSpeechOptions;
|
|
579
|
+
/** List of connected AI agents can be called by the current agent. Overrides the stored value. */
|
|
580
|
+
connectedAgents?: Array<AiConnectedAgentMetadata>;
|
|
581
|
+
/** List of connected AI agents can be called by the current agent. Overrides the stored value. */
|
|
582
|
+
connectedIntegrations?: Array<AiConnectedIntegrationMetadata>;
|
|
583
|
+
/** List of connected AiKnowlegeBases that can be called by the current agent */
|
|
584
|
+
connectedKnowledgeBases?: Array<AiConnectedKnowledgeBaseMetadata>;
|
|
585
|
+
/** Current budget for nested or recursive AI chat calls per single prompt. */
|
|
586
|
+
quotas?: AiChatPromptQuotas;
|
|
587
|
+
/**
|
|
588
|
+
* Include metadata in the context.
|
|
589
|
+
* @deprecated Use `includeMetadata` on individual `AiConnectedKnowledgeBaseMetadata` entries in `connectedKnowledgeBases` instead.
|
|
590
|
+
*/
|
|
591
|
+
includeMetadata?: boolean;
|
|
592
|
+
/** The temperature to use when sampling from the model. Default to 0.5. */
|
|
593
|
+
temperature?: number;
|
|
594
|
+
/** Preset instruction options that can be toggled on */
|
|
595
|
+
guardrails?: GuardrailsOptions;
|
|
596
|
+
/**
|
|
597
|
+
* Refuses prompts that carry PII before they reach the model. Read from the stored agent only —
|
|
598
|
+
* a value passed with a chat request is ignored, so a caller cannot switch off its own screening.
|
|
599
|
+
*/
|
|
600
|
+
pii?: AiPiiOptions;
|
|
601
|
+
/** The LLM model to use. Can be a vendor model name (string) or an integration-based model (object). */
|
|
602
|
+
model?: AiChatModelSelection;
|
|
603
|
+
/**
|
|
604
|
+
* The model to use when `model` cannot serve the conversation's very first request because its
|
|
605
|
+
* provider is unavailable — a rate limit, a capacity outage, or any other failure on the
|
|
606
|
+
* provider's side. A request that fails for its own reasons (an invalid prompt, a rejected
|
|
607
|
+
* schema, an exhausted Squid quota) is never retried on the backup, nor is any request after the
|
|
608
|
+
* first one, nor one that already produced output or ran a tool.
|
|
609
|
+
*
|
|
610
|
+
* A conversation that fell back then STAYS on that backup for the rest of its life, so an outage
|
|
611
|
+
* costs the primary's retry budget once rather than once per turn, and the model does not change
|
|
612
|
+
* mid-dialogue. The pin outlives the option that created it: changing or removing `backupModel`,
|
|
613
|
+
* changing the agent's own `model`, and the primary recovering all leave a pinned conversation
|
|
614
|
+
* where it is, and a pinned model that no longer resolves fails the request rather than moving the
|
|
615
|
+
* conversation. This is deliberate — a conversation accumulates provider-native file ids and a
|
|
616
|
+
* transcript in that provider's dialect, none of which survive a move. Pinning needs Squid-managed
|
|
617
|
+
* memory to have somewhere to record it; without memory every request is a first request anyway.
|
|
618
|
+
*
|
|
619
|
+
* A request carrying `fileIds` follows from the same reasoning, and the two cases differ. A first
|
|
620
|
+
* request does not fall back where that would cost it the attachments — to a model that cannot read
|
|
621
|
+
* ids the primary could, or that reads them without owning them — since answering from a model that
|
|
622
|
+
* never saw them is worse than reporting the outage. Where neither model reads file ids they are
|
|
623
|
+
* inert either way and the fallback proceeds. A
|
|
624
|
+
* conversation already pinned is held to less: it keeps running on its model, and if that model
|
|
625
|
+
* reads no file ids the ids are ignored there as they are anywhere else, because the alternative is
|
|
626
|
+
* a conversation that can never run again.
|
|
627
|
+
*
|
|
628
|
+
* Pass a model name for the model's own defaults, or a {@link BackupModelOptions} object to give
|
|
629
|
+
* the backup its own sampling settings. Everything else — instructions, functions, knowledge
|
|
630
|
+
* bases, connected agents, response format, memory — always comes from the primary configuration.
|
|
631
|
+
*
|
|
632
|
+
* On a turn the backup serves, the sampling settings are ITS settings alone: `temperature`,
|
|
633
|
+
* `reasoningEffort`, `maxTokens`, `maxOutputTokens` and `verbosity` are read from `backupModel`
|
|
634
|
+
* and nowhere else, so a value left unset there takes the backup model's own default even when
|
|
635
|
+
* the agent's profile or the request itself carries one. This holds for every turn of a pinned
|
|
636
|
+
* conversation, not only the one that fell back — tuning meant for one model is not evidence of
|
|
637
|
+
* what another should use.
|
|
638
|
+
*
|
|
639
|
+
* Applies to models served through Squid's own provider SDKs — the vendor models and
|
|
640
|
+
* `openai_compatible`, Bedrock and Vertex integrations. A model you serve yourself from backend
|
|
641
|
+
* code reports its failures as plain errors that carry no provider status, so a turn on one is
|
|
642
|
+
* never diagnosed as a provider outage and never falls back.
|
|
643
|
+
*
|
|
644
|
+
* The backup resolves its API key exactly as it would as the primary model, and is skipped
|
|
645
|
+
* silently when it cannot be resolved, when it reaches the same model as the primary, or when
|
|
646
|
+
* either model is a CLI-backed agent. Leave unset to keep a provider outage surfacing as an error.
|
|
647
|
+
*/
|
|
648
|
+
backupModel?: AiChatModelSelection | BackupModelOptions;
|
|
649
|
+
/** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
|
|
650
|
+
rerankProvider?: AiRerankProvider;
|
|
651
|
+
/**
|
|
652
|
+
* Options for AI agent execution plan, allowing the agent to perform an execution plan before invoking
|
|
653
|
+
* connected agents, connected integrations, or functions.
|
|
654
|
+
*/
|
|
655
|
+
executionPlanOptions?: AiAgentExecutionPlanOptions;
|
|
656
|
+
/** An array of file URLs to include in the chat context. */
|
|
657
|
+
fileUrls?: Array<AiFileUrl>;
|
|
658
|
+
/**
|
|
659
|
+
* Arbitrary client-defined annotations attached to this AI call for usage tracking.
|
|
660
|
+
* Reported as `annotation.<key>` tags on Squid AI usage metrics, so token usage can later be
|
|
661
|
+
* filtered and grouped by these values (e.g. `{ feature: 'support-bot', requestSource: 'mobile' }`).
|
|
662
|
+
* Inherited by nested calls to connected agents made while serving this call.
|
|
663
|
+
* Limits: at most 10 entries, keys up to 64 characters, values up to 256 characters;
|
|
664
|
+
* entries beyond the limits are dropped or truncated.
|
|
665
|
+
*/
|
|
666
|
+
metricAnnotations?: Record<string, string>;
|
|
667
|
+
/**
|
|
668
|
+
* The level of reasoning effort to apply; defaults to model-specific value.
|
|
669
|
+
* Effective only for models with reasoning.
|
|
670
|
+
*/
|
|
671
|
+
reasoningEffort?: AiReasoningEffort;
|
|
672
|
+
/**
|
|
673
|
+
* Controls response length and detail level.
|
|
674
|
+
* Use `low` for brief responses, `medium` for balanced detail, or `high` for comprehensive explanations.
|
|
675
|
+
* Default: 'medium'.
|
|
676
|
+
*
|
|
677
|
+
* Note: this parameter is only supported by OpenAI and is ignored for others. It applies to every
|
|
678
|
+
* response format, including `json_object` and `json_schema`.
|
|
679
|
+
* For other providers ask about verbosity in prompt and using `maxOutputTokens`.
|
|
680
|
+
*/
|
|
681
|
+
verbosity?: AiVerbosityLevel;
|
|
682
|
+
/**
|
|
683
|
+
* Enable LLMs built-in code interpreter for executing Python code.
|
|
684
|
+
* - 'none': Code interpreter is disabled (default).
|
|
685
|
+
* - 'llm': Use LLM's native code interpreter to run Python code.
|
|
686
|
+
*
|
|
687
|
+
* Note: Only supported by OpenAI, Anthropic and Gemini models. Ignored for other providers.
|
|
688
|
+
*/
|
|
689
|
+
useCodeInterpreter?: 'none' | 'llm';
|
|
690
|
+
/**
|
|
691
|
+
* File IDs to include in the chat context.
|
|
692
|
+
* These are IDs returned from the AI provider's Files API after uploading files.
|
|
693
|
+
* Files are attached to the conversation and can be read/analyzed by the AI.
|
|
694
|
+
*/
|
|
695
|
+
fileIds?: string[];
|
|
696
|
+
/**
|
|
697
|
+
* Timeout in milliseconds for one model-call attempt of the chat (a single provider call,
|
|
698
|
+
* covering that call's tool loop). An attempt that produced nothing by this deadline is treated
|
|
699
|
+
* as a stalled provider connection and retried per `retriesOnStall`, each retry getting this
|
|
700
|
+
* full budget again — so the provider phase of a chat may take up to
|
|
701
|
+
* `(1 + retriesOnStall) * timeoutMs` in the worst case. Defaults to 240,000 (4 minutes).
|
|
702
|
+
*/
|
|
703
|
+
timeoutMs?: number;
|
|
704
|
+
/**
|
|
705
|
+
* How many times a stalled model-call attempt is reissued. A retry happens only when the
|
|
706
|
+
* attempt hit `timeoutMs` having produced nothing AND no AI function has executed in the turn,
|
|
707
|
+
* so a retry can never repeat a side effect; aborting the stalled attempt destroys its
|
|
708
|
+
* connection, so the retry cannot reuse it. `0` disables stall retries. Defaults to 1.
|
|
709
|
+
*/
|
|
710
|
+
retriesOnStall?: number;
|
|
711
|
+
/** Maximum number of tool-call iterations the model may perform in a single chat turn. Defaults to 50. */
|
|
712
|
+
maxToolIterations?: number;
|
|
713
|
+
}
|
|
714
|
+
/**
|
|
715
|
+
* Chat options specific to Gemini models, extending base options.
|
|
716
|
+
* @category AI
|
|
717
|
+
*/
|
|
718
|
+
export interface GeminiChatOptions extends BaseAiChatOptions {
|
|
719
|
+
/** The Gemini model to use for the chat. */
|
|
720
|
+
model?: GeminiChatModelName;
|
|
721
|
+
/** Enables grounding with web search for more informed responses; defaults to false. */
|
|
722
|
+
groundingWithWebSearch?: boolean;
|
|
723
|
+
}
|
|
724
|
+
/**
|
|
725
|
+
* Chat options specific to Grok models, extending base options.
|
|
726
|
+
* @category AI
|
|
727
|
+
*/
|
|
728
|
+
export interface GrokChatOptions extends BaseAiChatOptions {
|
|
729
|
+
/** The Grok model to use for the chat. */
|
|
730
|
+
model?: GrokChatModelName;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* Chat options specific to OpenAI models, extending base options.
|
|
734
|
+
* @category AI
|
|
735
|
+
*/
|
|
736
|
+
export interface OpenAiChatOptions extends BaseAiChatOptions {
|
|
737
|
+
/** The OpenAI model to use for the chat. */
|
|
738
|
+
model?: OpenAiChatModelName;
|
|
739
|
+
}
|
|
740
|
+
/**
|
|
741
|
+
* Canonical reasoning-effort levels, ordered from least to most effort. These are the values that
|
|
742
|
+
* have a defined position on the effort axis and therefore participate in clamping when a model does
|
|
743
|
+
* not support the exact requested level.
|
|
744
|
+
* @category AI
|
|
745
|
+
*/
|
|
746
|
+
export type { CanonicalReasoningEffort } from './ai-common.public-types';
|
|
747
|
+
/**
|
|
748
|
+
* AI reasoning effort. Pass one of the canonical levels for portable, autocomplete-friendly usage, or
|
|
749
|
+
* a raw provider-native string when a model exposes a level outside the canonical set.
|
|
750
|
+
*
|
|
751
|
+
* Resolution against the selected model (see {@link ReasoningCapability}):
|
|
752
|
+
* - exact match with the model's capability -> used as-is (1:1);
|
|
753
|
+
* - canonical level the model lacks -> clamped to the nearest supported level (ties resolve downward);
|
|
754
|
+
* - unknown string the model cannot place on the axis -> dropped, so the model's own default applies,
|
|
755
|
+
* with a warning;
|
|
756
|
+
* - model without a reasoning knob -> ignored, with a warning.
|
|
757
|
+
*
|
|
758
|
+
* A model served through an `openai_compatible` integration is the exception: the value is sent to
|
|
759
|
+
* that endpoint exactly as written, with none of the resolution above, since the endpoint's model is
|
|
760
|
+
* the app's own choice and this registry cannot describe it. That is also how to reach a level the
|
|
761
|
+
* canonical set has no name for.
|
|
762
|
+
* @category AI
|
|
763
|
+
*/
|
|
764
|
+
export type AiReasoningEffort = CanonicalReasoningEffort | (string & {});
|
|
765
|
+
/**
|
|
766
|
+
* Declares how a model exposes reasoning effort. Used as the single source of truth for resolving a
|
|
767
|
+
* requested {@link AiReasoningEffort} onto what the model natively accepts. When a request cannot be
|
|
768
|
+
* matched or clamped, no reasoning parameter is emitted and the model applies its own native default.
|
|
769
|
+
*
|
|
770
|
+
* - `none`: the model has no reasoning knob (e.g. it always reasons).
|
|
771
|
+
* - `levels`: the model accepts a fixed set of named levels (emitted as a string).
|
|
772
|
+
* - `budget`: the model accepts a token budget; each canonical level maps to a concrete integer.
|
|
773
|
+
* @category AI
|
|
774
|
+
*/
|
|
775
|
+
export type ReasoningCapability = {
|
|
776
|
+
kind: 'none';
|
|
777
|
+
} | {
|
|
778
|
+
kind: 'levels';
|
|
779
|
+
supported: AiReasoningEffort[];
|
|
780
|
+
} | {
|
|
781
|
+
kind: 'budget';
|
|
782
|
+
perLevel: Partial<Record<CanonicalReasoningEffort, number>>;
|
|
783
|
+
};
|
|
784
|
+
/**
|
|
785
|
+
* Controls response length and detail level.
|
|
786
|
+
* Use `low` for brief responses,`medium` for balanced detail, or `high` for comprehensive explanations.
|
|
787
|
+
* Default: 'medium'.
|
|
788
|
+
*/
|
|
789
|
+
export type AiVerbosityLevel = 'low' | 'medium' | 'high';
|
|
790
|
+
/**
|
|
791
|
+
* Chat options specific to Anthropic models, extending base options.
|
|
792
|
+
*
|
|
793
|
+
* **Structured Outputs:**
|
|
794
|
+
* Anthropic models support structured outputs
|
|
795
|
+
* through the `responseFormat` field. Pass an object with `type: 'json_schema'` and a JSON schema
|
|
796
|
+
* to guarantee the response conforms exactly to your schema.
|
|
797
|
+
*
|
|
798
|
+
* **Example:**
|
|
799
|
+
* ```typescript
|
|
800
|
+
* {
|
|
801
|
+
* model: 'claude-sonnet-5-5',
|
|
802
|
+
* responseFormat: {
|
|
803
|
+
* type: 'json_schema',
|
|
804
|
+
* schema: {
|
|
805
|
+
* type: 'object',
|
|
806
|
+
* properties: {
|
|
807
|
+
* name: { type: 'string' },
|
|
808
|
+
* age: { type: 'number' }
|
|
809
|
+
* },
|
|
810
|
+
* required: ['name', 'age'],
|
|
811
|
+
* additionalProperties: false
|
|
812
|
+
* }
|
|
813
|
+
* }
|
|
814
|
+
* }
|
|
815
|
+
* ```
|
|
816
|
+
*
|
|
817
|
+
* @see https://docs.anthropic.com/en/docs/build-with-claude/structured-outputs
|
|
818
|
+
* @category AI
|
|
819
|
+
*/
|
|
820
|
+
export interface AnthropicChatOptions extends BaseAiChatOptions {
|
|
821
|
+
/** The Anthropic model to use for the chat. */
|
|
822
|
+
model?: AnthropicChatModelName;
|
|
823
|
+
}
|
|
824
|
+
/**
|
|
825
|
+
* The generic options type. When no generic is provided,
|
|
826
|
+
* the type is inferred from the provided overrideModel (or falls back to BaseAiAgentChatOptions).
|
|
827
|
+
* @category AI
|
|
828
|
+
*/
|
|
829
|
+
export type AiChatOptions<T extends AiChatModelSelection | undefined = undefined> = T extends undefined ? BaseAiChatOptions | GeminiChatOptions | OpenAiChatOptions | AnthropicChatOptions : T extends GeminiChatModelName ? GeminiChatOptions : T extends OpenAiChatModelName ? OpenAiChatOptions : T extends AnthropicChatModelName ? AnthropicChatOptions : T extends GrokChatModelName ? GrokChatOptions : BaseAiChatOptions;
|
|
830
|
+
/**
|
|
831
|
+
* @category AI
|
|
832
|
+
*/
|
|
833
|
+
export type AllAiAgentChatOptions = {
|
|
834
|
+
[K in keyof BaseAiChatOptions | keyof GeminiChatOptions | keyof GrokChatOptions | keyof OpenAiChatOptions | keyof AnthropicChatOptions]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof GrokChatOptions ? GrokChatOptions[K] : never) | (K extends keyof OpenAiChatOptions ? OpenAiChatOptions[K] : never) | (K extends keyof AnthropicChatOptions ? AnthropicChatOptions[K] : never);
|
|
835
|
+
};
|
|
836
|
+
/**
|
|
837
|
+
* Credentials a caller sends with one chat request. The client sends them in the `x-squid-integration-access-tokens`
|
|
838
|
+
* request header rather than with the options, so they reach only the tools that run with them and are never stored
|
|
839
|
+
* with the agent.
|
|
840
|
+
* @category AI
|
|
841
|
+
*/
|
|
842
|
+
export interface AiChatRequestCredentials {
|
|
843
|
+
/**
|
|
844
|
+
* Access tokens keyed by integration ID. The integration's tools run with its token for this request when the
|
|
845
|
+
* integration type supports it; other types ignore it.
|
|
846
|
+
*/
|
|
847
|
+
integrationAccessTokens?: Record<IntegrationId, string>;
|
|
848
|
+
}
|
|
849
|
+
/**
|
|
850
|
+
* Configuration for exposing an AI agent as an MCP server at `/mcp/<agentId>`.
|
|
851
|
+
* @category AI
|
|
852
|
+
*/
|
|
853
|
+
export interface AiAgentMcpServerConfig {
|
|
854
|
+
/** Whether the agent is exposed as an MCP server. */
|
|
855
|
+
enabled: boolean;
|
|
856
|
+
/**
|
|
857
|
+
* Description of the MCP server, served as the `instructions` field of the MCP initialize
|
|
858
|
+
* result. Defaults to the agent description when not provided.
|
|
859
|
+
*/
|
|
860
|
+
description?: string;
|
|
861
|
+
/**
|
|
862
|
+
* Description of the MCP `ask` tool, exposed in the tools manifest.
|
|
863
|
+
* Defaults to a generic ask-the-agent description when not provided.
|
|
864
|
+
*/
|
|
865
|
+
toolDescription?: string;
|
|
866
|
+
/**
|
|
867
|
+
* ID of an auth integration used to OAuth-protect the MCP server. When set, MCP requests must
|
|
868
|
+
* include a valid bearer token from this integration. Without this and `requireApiKey`, the
|
|
869
|
+
* MCP endpoint is public.
|
|
870
|
+
*/
|
|
871
|
+
oauthIntegrationId?: IntegrationId;
|
|
872
|
+
/**
|
|
873
|
+
* When true, MCP requests must present the agent's API key as a bearer token
|
|
874
|
+
* (`Authorization: Bearer <agent API key>` or the `x-squid-agent-api-key` header). Can be
|
|
875
|
+
* combined with `oauthIntegrationId`, in which case either credential is accepted.
|
|
876
|
+
*/
|
|
877
|
+
requireApiKey?: boolean;
|
|
878
|
+
}
|
|
879
|
+
/**
|
|
880
|
+
* Request to AI-generate the MCP server and tool descriptions for an agent based on its
|
|
881
|
+
* instructions and connected resources.
|
|
882
|
+
* @category AI
|
|
883
|
+
*/
|
|
884
|
+
export interface GenerateAgentMcpDescriptionsRequest {
|
|
885
|
+
/** The ID of the agent to generate MCP descriptions for. */
|
|
886
|
+
agentId: AiAgentId;
|
|
887
|
+
}
|
|
888
|
+
/**
|
|
889
|
+
* AI-generated MCP descriptions for an agent. Returned without persisting — the caller saves them
|
|
890
|
+
* onto the agent's MCP server configuration.
|
|
891
|
+
* @category AI
|
|
892
|
+
*/
|
|
893
|
+
export interface GenerateAgentMcpDescriptionsResponse {
|
|
894
|
+
/** Generated description of the MCP server. */
|
|
895
|
+
description: string;
|
|
896
|
+
/** Generated description of the MCP `ask` tool. */
|
|
897
|
+
toolDescription: string;
|
|
898
|
+
}
|
|
899
|
+
/**
|
|
900
|
+
* A definition of an AI agent with its properties and default chat options.
|
|
901
|
+
* @category AI
|
|
902
|
+
*/
|
|
903
|
+
export interface AiAgent<T extends AiChatModelSelection | undefined = undefined> {
|
|
904
|
+
/** The unique identifier of the AI agent. */
|
|
905
|
+
id: AiAgentId;
|
|
906
|
+
/** The date and time the agent was created. */
|
|
907
|
+
createdAt: Date;
|
|
908
|
+
/** The date and time the agent was last updated. */
|
|
909
|
+
updatedAt: Date;
|
|
910
|
+
/** An optional description of the agent's purpose or capabilities. */
|
|
911
|
+
description?: string;
|
|
912
|
+
/** Indicates whether the agent is publicly accessible; defaults to false. */
|
|
913
|
+
isPublic?: boolean;
|
|
914
|
+
/** Enables audit logging for the agent's activities if true; defaults to false. */
|
|
915
|
+
auditLog?: boolean;
|
|
916
|
+
/** Records the full agent context in the audit log — assembled system instructions on the chat-start entry and retrieved knowledge-base content in KB tool-call updates; requires auditLog; defaults to false. */
|
|
917
|
+
auditLogFullContext?: boolean;
|
|
918
|
+
/** The default chat options for the agent, overridable by the user during use. */
|
|
919
|
+
options: AiChatOptions<T>;
|
|
920
|
+
/** Optional api key used specifically for operations on this agent */
|
|
921
|
+
apiKey?: string;
|
|
922
|
+
/** Optional configuration for exposing the agent as an MCP server. */
|
|
923
|
+
mcpServer?: AiAgentMcpServerConfig;
|
|
924
|
+
}
|
|
925
|
+
/**
|
|
926
|
+
* @category AI
|
|
927
|
+
*/
|
|
928
|
+
export type UpsertAgentRequest = Omit<AiAgent, 'createdAt' | 'updatedAt' | 'options'> & {
|
|
929
|
+
options?: AiChatOptions;
|
|
930
|
+
};
|
|
931
|
+
/**
|
|
932
|
+
* Status update title broadcast when the agent finishes producing a response,
|
|
933
|
+
* either successfully or with an error. Emitted exactly once per `ask` job and
|
|
934
|
+
* is the last status event for that job.
|
|
935
|
+
* @category AI
|
|
936
|
+
*/
|
|
937
|
+
export declare const AGENT_STATUS_TITLE_AGENT_RESPONSE = "Agent Response";
|
|
938
|
+
/**
|
|
939
|
+
* Status update title broadcast when the agent invokes a knowledge-base
|
|
940
|
+
* callable. A matching invocation produces a single event with this title.
|
|
941
|
+
* @category AI
|
|
942
|
+
*/
|
|
943
|
+
export declare const AGENT_STATUS_TITLE_ACCESSING_KB = "Accessing Knowledge Base";
|
|
944
|
+
/**
|
|
945
|
+
* Status update title broadcast when the agent invokes an AI function callable
|
|
946
|
+
* (a backend `@aiFunction`). Lets a caller detect that a function was actually
|
|
947
|
+
* called, independent of how the model renders the result in its final answer.
|
|
948
|
+
* @category AI
|
|
949
|
+
*/
|
|
950
|
+
export declare const AGENT_STATUS_TITLE_CALLING_AI_FUNCTION = "Calling AI Function";
|
|
951
|
+
/**
|
|
952
|
+
* Status update title broadcast when an AI function callable returns, carrying the function's raw
|
|
953
|
+
* result in the body. Nested under the matching {@link AGENT_STATUS_TITLE_CALLING_AI_FUNCTION} event.
|
|
954
|
+
* @category AI
|
|
955
|
+
*/
|
|
956
|
+
export declare const AGENT_STATUS_TITLE_AI_FUNCTION_RESULT = "AI Function Result";
|
|
957
|
+
/**
|
|
958
|
+
* Status update title broadcast when the agent invokes a knowledge-base metadata-inspection callable
|
|
959
|
+
* (the opt-in `enableMetadataInspection` tool). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB}
|
|
960
|
+
* so a caller can tell a metadata-value inspection apart from an ordinary KB search.
|
|
961
|
+
* @category AI
|
|
962
|
+
*/
|
|
963
|
+
export declare const AGENT_STATUS_TITLE_INSPECTING_KB_METADATA = "Inspecting Knowledge Base Metadata";
|
|
964
|
+
/**
|
|
965
|
+
* Status update title broadcast when the agent invokes the knowledge-graph query callable (offered
|
|
966
|
+
* automatically for graph-enabled KBs). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB} so a
|
|
967
|
+
* caller can tell graph navigation apart from an ordinary KB search.
|
|
968
|
+
* @category AI
|
|
969
|
+
*/
|
|
970
|
+
export declare const AGENT_STATUS_TITLE_QUERYING_KB_GRAPH = "Querying Knowledge Base Graph";
|
|
971
|
+
/**
|
|
972
|
+
* Status update title emitted when the agent runs the `grepKnowledgeBase` tool (a literal/regex scan over
|
|
973
|
+
* the knowledge base's raw extracted text). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB} so a
|
|
974
|
+
* caller can tell an exact-match scan apart from ranked retrieval.
|
|
975
|
+
* @category AI
|
|
976
|
+
*/
|
|
977
|
+
export declare const AGENT_STATUS_TITLE_GREPPING_KB = "Searching Knowledge Base Text";
|
|
978
|
+
/**
|
|
979
|
+
* Status update title broadcast when the agent queries a spreadsheet file callable.
|
|
980
|
+
* @category AI
|
|
981
|
+
*/
|
|
982
|
+
export declare const AGENT_STATUS_TITLE_QUERYING_SPREADSHEET = "Querying Spreadsheet";
|
|
983
|
+
/**
|
|
984
|
+
* A status message from an AI agent operation.
|
|
985
|
+
* @category AI
|
|
986
|
+
*/
|
|
987
|
+
export interface AiStatusMessage {
|
|
988
|
+
/** ID of the status update message. */
|
|
989
|
+
messageId: string;
|
|
990
|
+
/** The ID of the agent generating the status message. */
|
|
991
|
+
agentId?: AiAgentId;
|
|
992
|
+
/** An optional chat ID associated with the status message. */
|
|
993
|
+
chatId?: string;
|
|
994
|
+
/** The title or summary of the status message. */
|
|
995
|
+
title: string;
|
|
996
|
+
/** Markdown body content for the status update. */
|
|
997
|
+
body: string;
|
|
998
|
+
/** ID of the parent status update for nested display. */
|
|
999
|
+
parentStatusUpdateId?: string;
|
|
1000
|
+
/** The Job ID associated with the status message. */
|
|
1001
|
+
jobId: JobId;
|
|
1002
|
+
/** Optional tags providing additional metadata about the status. */
|
|
1003
|
+
tags?: Record<string, any>;
|
|
1004
|
+
}
|
|
1005
|
+
/**
|
|
1006
|
+
* `errorType` on a failed chat/ask job when the AI provider itself failed (a stall, timeout, or
|
|
1007
|
+
* unrecognized 5xx) rather than Squid or the caller's request.
|
|
1008
|
+
* @category AI
|
|
1009
|
+
*/
|
|
1010
|
+
export declare const AI_PROVIDER_ERROR_TYPE = "AI_PROVIDER_ERROR";
|
|
1011
|
+
/** List of all chat history (memory) sources. */
|
|
1012
|
+
export declare const AI_CHAT_MESSAGE_SOURCE: readonly ["user", "ai"];
|
|
1013
|
+
/** Source of the chat history entry: either an AI response or a user. */
|
|
1014
|
+
export type AiChatMessageSource = (typeof AI_CHAT_MESSAGE_SOURCE)[number];
|
|
1015
|
+
/** A history entry for a chat. */
|
|
1016
|
+
export interface AiChatMessage {
|
|
1017
|
+
/** ID of the entry. Unique per agent. */
|
|
1018
|
+
id: string;
|
|
1019
|
+
/** Agent's application. */
|
|
1020
|
+
appId: AppId;
|
|
1021
|
+
/** The ID of the agent that owns the history. */
|
|
1022
|
+
agentId: AiAgentId;
|
|
1023
|
+
/** A memory (history) ID associated with the chat conversation. */
|
|
1024
|
+
memoryId: string;
|
|
1025
|
+
/** The source of the message: a user or an AI. */
|
|
1026
|
+
source: AiChatMessageSource;
|
|
1027
|
+
/** The text of the entry: a user's prompt or an AI-generated response. */
|
|
1028
|
+
message: string;
|
|
1029
|
+
/** Time the entry is created. Unix time millis. */
|
|
1030
|
+
timestamp: number;
|
|
1031
|
+
}
|
|
1032
|
+
/**
|
|
1033
|
+
* A single chunk of data returned from an AI search operation.
|
|
1034
|
+
* @category AI
|
|
1035
|
+
*/
|
|
1036
|
+
export interface AiSearchResultChunk {
|
|
1037
|
+
/** The data content of the search result chunk. */
|
|
1038
|
+
data: string;
|
|
1039
|
+
/** Optional metadata associated with the chunk. */
|
|
1040
|
+
metadata?: AiContextMetadata;
|
|
1041
|
+
/** The relevance score of the chunk, indicating match quality. */
|
|
1042
|
+
score: number;
|
|
1043
|
+
}
|
|
1044
|
+
/**
|
|
1045
|
+
* Represents an AI agent's context entry with metadata and content.
|
|
1046
|
+
* @category AI
|
|
1047
|
+
*/
|
|
1048
|
+
export interface AiAgentContext {
|
|
1049
|
+
/** The unique identifier of the context entry. */
|
|
1050
|
+
id: AiContextId;
|
|
1051
|
+
/** The date and time the context was created. */
|
|
1052
|
+
createdAt: Date;
|
|
1053
|
+
/** The date and time the context was last updated. */
|
|
1054
|
+
updatedAt: Date;
|
|
1055
|
+
/** The ID of the agent owning this context. */
|
|
1056
|
+
agentId: AiAgentId;
|
|
1057
|
+
/** The type of context (e.g., 'text' or 'file'). */
|
|
1058
|
+
type: AiKnowledgeBaseContextType;
|
|
1059
|
+
/** A title describing the context content. */
|
|
1060
|
+
title: string;
|
|
1061
|
+
/** The text content of the context. */
|
|
1062
|
+
text: string;
|
|
1063
|
+
/** Indicates whether the context is a preview; defaults to false. */
|
|
1064
|
+
preview: boolean;
|
|
1065
|
+
/** The size of the context content in bytes. */
|
|
1066
|
+
sizeBytes: number;
|
|
1067
|
+
/** Metadata associated with the context. */
|
|
1068
|
+
metadata: AiContextMetadata;
|
|
1069
|
+
}
|
|
1070
|
+
/**
|
|
1071
|
+
* @category AI
|
|
1072
|
+
*/
|
|
1073
|
+
export type AgentContextRequest = TextContextRequest | FileContextRequest;
|
|
1074
|
+
/**
|
|
1075
|
+
* Base fields shared by all agent context requests.
|
|
1076
|
+
* @category AI
|
|
1077
|
+
*/
|
|
1078
|
+
export interface BaseContextRequest {
|
|
1079
|
+
/** The unique identifier of the context item. */
|
|
1080
|
+
contextId: string;
|
|
1081
|
+
/** The type of the context content. */
|
|
1082
|
+
type: AiKnowledgeBaseContextType;
|
|
1083
|
+
/** Optional metadata associated with the context item. */
|
|
1084
|
+
metadata?: AiContextMetadata;
|
|
1085
|
+
}
|
|
1086
|
+
/**
|
|
1087
|
+
* Status of an individual context item after successfully upserting it.
|
|
1088
|
+
* @category AI
|
|
1089
|
+
*/
|
|
1090
|
+
export interface BaseUpsertContextStatus {
|
|
1091
|
+
/** Whether the context upsert was successful, otherwise, what occurred. */
|
|
1092
|
+
status: 'success' | 'error';
|
|
1093
|
+
/** The unique identifier of the context item. */
|
|
1094
|
+
contextId: string;
|
|
1095
|
+
/** The name of the context item, typically the title or filename. */
|
|
1096
|
+
name: string;
|
|
1097
|
+
}
|
|
1098
|
+
/**
|
|
1099
|
+
* An image whose description failed during ingestion: the context is stored without that image's chunk.
|
|
1100
|
+
* @category AI
|
|
1101
|
+
*/
|
|
1102
|
+
export interface ContextImageFailure {
|
|
1103
|
+
/** Zero-based index of the page carrying the image. */
|
|
1104
|
+
pageIndex: number;
|
|
1105
|
+
/** Extraction-assigned id of the image within the document. */
|
|
1106
|
+
imageId: string;
|
|
1107
|
+
/** Why describing the image failed. */
|
|
1108
|
+
errorMessage: string;
|
|
1109
|
+
}
|
|
1110
|
+
/**
|
|
1111
|
+
* Status of an individual context item after successfully upserting it.
|
|
1112
|
+
* @category AI
|
|
1113
|
+
*/
|
|
1114
|
+
export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
|
|
1115
|
+
/** Whether the context upsert was successful or got an error. */
|
|
1116
|
+
status: 'success';
|
|
1117
|
+
/**
|
|
1118
|
+
* Set when the context was stored and is fully searchable (vector/keyword), but was NOT graph-indexed
|
|
1119
|
+
* because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent;
|
|
1120
|
+
* surfaced so bulk operations can report which contexts fell outside the graph.
|
|
1121
|
+
*/
|
|
1122
|
+
graphIndexingSkipped?: boolean;
|
|
1123
|
+
/** First failed images (capped); absent when every image succeeded. `imageFailureCount` is the total. */
|
|
1124
|
+
imageFailures?: Array<ContextImageFailure>;
|
|
1125
|
+
/** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
|
|
1126
|
+
imageFailureCount?: number;
|
|
1127
|
+
}
|
|
1128
|
+
/**
|
|
1129
|
+
* Names an upsert failure; `DUPLICATE_CONTENT` identifies existing content when contextId is omitted.
|
|
1130
|
+
* `EMBEDDING_FAILED`, `EXTRACTION_TIMED_OUT`, `PROVIDER_ACCESS_DENIED`, and `SOURCE_UNREACHABLE` may
|
|
1131
|
+
* succeed on retry. Document faults carry `retryable: false` because the same bytes fail again.
|
|
1132
|
+
* @category AI
|
|
1133
|
+
*/
|
|
1134
|
+
export type UpsertContextErrorCode = 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'IMAGE_OVER_PROVIDER_LIMIT' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_DOCUMENT' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
|
|
1135
|
+
/**
|
|
1136
|
+
* The existing context a `DUPLICATE_CONTENT` rejection points at — where the byte-identical original
|
|
1137
|
+
* already lives.
|
|
1138
|
+
* @category AI
|
|
1139
|
+
*/
|
|
1140
|
+
export interface UpsertContextDuplicateOf {
|
|
1141
|
+
/** The id of the already-stored context whose content is byte-identical to the rejected request. */
|
|
1142
|
+
contextId: string;
|
|
1143
|
+
/** The existing context's source reference (file name / URL), when it has one. */
|
|
1144
|
+
reference?: string;
|
|
1145
|
+
/** The existing context's `folderPath` metadata, when it was ingested with a folder path. */
|
|
1146
|
+
folderPath?: string;
|
|
1147
|
+
}
|
|
1148
|
+
/**
|
|
1149
|
+
* Status of an individual context item after it failed to upsert.
|
|
1150
|
+
*
|
|
1151
|
+
* Contains the error message for why the upsert failed.
|
|
1152
|
+
* @category AI
|
|
1153
|
+
*/
|
|
1154
|
+
export interface UpsertContextStatusError extends BaseUpsertContextStatus {
|
|
1155
|
+
/** Whether the context upsert was successful or got an error. */
|
|
1156
|
+
status: 'error';
|
|
1157
|
+
/** Reason the upsert failed. */
|
|
1158
|
+
errorMessage: string;
|
|
1159
|
+
/** Machine-readable code for the failure, when one applies. */
|
|
1160
|
+
errorCode?: UpsertContextErrorCode;
|
|
1161
|
+
/**
|
|
1162
|
+
* Present only when the same bytes fail the same way again, so a caller must not retry the request
|
|
1163
|
+
* as-is. Absence means the failure may be transient.
|
|
1164
|
+
*/
|
|
1165
|
+
retryable?: false;
|
|
1166
|
+
/**
|
|
1167
|
+
* The existing context this request duplicated, when `errorCode` is `DUPLICATE_CONTENT`. Lets a caller
|
|
1168
|
+
* point the user at where the original already lives (e.g. its folder) instead of only reporting the
|
|
1169
|
+
* rejection. `reference`/`folderPath` are present when the existing context carries them.
|
|
1170
|
+
*/
|
|
1171
|
+
duplicateOf?: UpsertContextDuplicateOf;
|
|
1172
|
+
/** First failed images (capped) when every image failed and the document had no text; otherwise absent. */
|
|
1173
|
+
imageFailures?: Array<ContextImageFailure>;
|
|
1174
|
+
/** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
|
|
1175
|
+
imageFailureCount?: number;
|
|
1176
|
+
}
|
|
1177
|
+
/**
|
|
1178
|
+
* Status of an individual context item after attempting to upsert it.
|
|
1179
|
+
* @category AI
|
|
1180
|
+
*/
|
|
1181
|
+
export type UpsertContextStatus = UpsertContextStatusSuccess | UpsertContextStatusError;
|
|
1182
|
+
/**
|
|
1183
|
+
* Response structure for upserting context.
|
|
1184
|
+
* @category AI
|
|
1185
|
+
*/
|
|
1186
|
+
export interface UpsertAgentContextResponse {
|
|
1187
|
+
/** Upsert failure that occurred for the items sent in the request. */
|
|
1188
|
+
failure?: UpsertContextStatusError;
|
|
1189
|
+
}
|
|
1190
|
+
/**
|
|
1191
|
+
* Response structure for upserting contexts.
|
|
1192
|
+
* @category AI
|
|
1193
|
+
*/
|
|
1194
|
+
export interface UpsertAgentContextsResponse {
|
|
1195
|
+
/** List of the upsert failures that occurred for the items sent in the request. */
|
|
1196
|
+
failures: Array<UpsertContextStatusError>;
|
|
1197
|
+
}
|
|
1198
|
+
/**
|
|
1199
|
+
* Base options for upserting text content into the AI agent's context.
|
|
1200
|
+
* @category AI
|
|
1201
|
+
*/
|
|
1202
|
+
export interface AiContextTextOptions extends BaseAiContextOptions {
|
|
1203
|
+
}
|
|
1204
|
+
/**
|
|
1205
|
+
* Base options for upserting file content into the AI agent's context.
|
|
1206
|
+
* @category AI
|
|
1207
|
+
*/
|
|
1208
|
+
export interface AiContextFileOptions extends BaseAiContextOptions {
|
|
1209
|
+
}
|
|
1210
|
+
/**
|
|
1211
|
+
* Request structure for adding text-based context to an AI agent.
|
|
1212
|
+
* @category AI
|
|
1213
|
+
*/
|
|
1214
|
+
export interface TextContextRequest extends BaseContextRequest {
|
|
1215
|
+
/** Specifies the context type as 'text'. */
|
|
1216
|
+
type: 'text';
|
|
1217
|
+
/** A title for the text context. */
|
|
1218
|
+
title: string;
|
|
1219
|
+
/** The text content to add to the context. */
|
|
1220
|
+
text: string;
|
|
1221
|
+
/** General options for how to process the text. */
|
|
1222
|
+
options?: AiContextTextOptions;
|
|
1223
|
+
}
|
|
1224
|
+
/**
|
|
1225
|
+
* Request structure for adding file-based context to an AI agent.
|
|
1226
|
+
* @category AI
|
|
1227
|
+
*/
|
|
1228
|
+
export interface FileContextRequest extends BaseContextRequest {
|
|
1229
|
+
/** Specifies the context type as 'file'. */
|
|
1230
|
+
type: 'file';
|
|
1231
|
+
/**
|
|
1232
|
+
* Whether to extract images from the file, describe them with a vision model, and index those
|
|
1233
|
+
* descriptions alongside the text. Defaults to true — a document's charts, diagrams and scanned pages
|
|
1234
|
+
* carry content the text layer does not. Note that the text context request has no such option:
|
|
1235
|
+
* inline images in a text payload are extracted only for a knowledge-base text context, and default
|
|
1236
|
+
* to OFF there.
|
|
1237
|
+
*/
|
|
1238
|
+
extractImages?: boolean;
|
|
1239
|
+
/** The minimum size for extracted images, if applicable. */
|
|
1240
|
+
imageMinSizePixels?: number;
|
|
1241
|
+
/** The AI model to use for extraction, if specified. */
|
|
1242
|
+
extractionModel?: AiChatModelSelection;
|
|
1243
|
+
/** General options for how to process the file. */
|
|
1244
|
+
options?: AiContextFileOptions;
|
|
1245
|
+
/** The preferred method for extracting data from the document. */
|
|
1246
|
+
preferredExtractionMethod?: DocumentExtractionMethod;
|
|
1247
|
+
/**
|
|
1248
|
+
* Whether Squid keeps or discards the original file.
|
|
1249
|
+
*
|
|
1250
|
+
* Keeping the original file allows reprocessing and the ability for the user to download it later.
|
|
1251
|
+
*
|
|
1252
|
+
* Defaults to false.
|
|
1253
|
+
*/
|
|
1254
|
+
discardOriginalFile?: boolean;
|
|
1255
|
+
}
|
|
1256
|
+
/**
|
|
1257
|
+
* Base options for how to deal with the content being upserted.
|
|
1258
|
+
* @category AI
|
|
1259
|
+
*/
|
|
1260
|
+
export type BaseAiContextOptions = {
|
|
1261
|
+
/** The type of RAG to use for the content. */
|
|
1262
|
+
ragType?: AiRagType;
|
|
1263
|
+
/** Amount of chunk overlap, in characters. */
|
|
1264
|
+
chunkOverlap?: number;
|
|
1265
|
+
};
|
|
1266
|
+
/**
|
|
1267
|
+
* @category AI
|
|
1268
|
+
*/
|
|
1269
|
+
export type GuardrailKeysType = 'disableProfanity' | 'offTopicAnswers' | 'professionalTone' | 'disablePii';
|
|
1270
|
+
/**
|
|
1271
|
+
* Options for applying guardrails to AI responses to enforce specific constraints.
|
|
1272
|
+
* @category AI
|
|
1273
|
+
*/
|
|
1274
|
+
export type GuardrailsOptions = {
|
|
1275
|
+
/** Disables profanity in the AI response if true; defaults to false. */
|
|
1276
|
+
disableProfanity?: boolean;
|
|
1277
|
+
/** Prevents off-topic answers if true; defaults to false. */
|
|
1278
|
+
offTopicAnswers?: boolean;
|
|
1279
|
+
/** Enforces a professional tone in the response if true; defaults to false. */
|
|
1280
|
+
professionalTone?: boolean;
|
|
1281
|
+
/** Disables inclusion of personally identifiable information if true; defaults to false. */
|
|
1282
|
+
disablePii?: boolean;
|
|
1283
|
+
/** A custom guardrail instruction, if specified. */
|
|
1284
|
+
custom?: string;
|
|
1285
|
+
};
|
|
1286
|
+
/**
|
|
1287
|
+
* PII kinds a prompt can be screened for. Each one is judged in context by the screening model, so
|
|
1288
|
+
* a value is classified by what the prompt says it is rather than by which format it happens to fit.
|
|
1289
|
+
* @category AI
|
|
1290
|
+
*/
|
|
1291
|
+
export type AiPiiEntityType = 'email' | 'phoneNumber' | 'creditCard' | 'ssn' | 'iban' | 'passport';
|
|
1292
|
+
/** Entity kinds screened when {@link AiPiiOptions.entities} is omitted. */
|
|
1293
|
+
export declare const DEFAULT_PII_ENTITY_TYPES: ReadonlyArray<AiPiiEntityType>;
|
|
1294
|
+
/** Model that screens prompts unless overridden. Small and fast: it runs on every prompt. */
|
|
1295
|
+
export declare const DEFAULT_PII_CLASSIFIER_MODEL = "gpt-6-luna";
|
|
1296
|
+
/**
|
|
1297
|
+
* Rejects a prompt before it reaches the agent's model when it carries PII, so the prompt is never
|
|
1298
|
+
* sent to the model provider, never answered, and never written to chat memory.
|
|
1299
|
+
*
|
|
1300
|
+
* Screening is one {@link classifierModel} call per prompt, covering {@link entities} and
|
|
1301
|
+
* {@link customRules} together. Because a model does the reading rather than a pattern, a value is
|
|
1302
|
+
* judged by what the prompt says it is, and app-specific identifiers can be described in plain
|
|
1303
|
+
* language instead of expressed as a format.
|
|
1304
|
+
*
|
|
1305
|
+
* This is the inverse of {@link GuardrailsOptions.disablePii}, which asks the agent's own model not
|
|
1306
|
+
* to *emit* PII in its answer.
|
|
1307
|
+
* @category AI
|
|
1308
|
+
*/
|
|
1309
|
+
export type AiPiiOptions = {
|
|
1310
|
+
/** `reject` refuses a prompt carrying PII; `off` (default) disables screening entirely. */
|
|
1311
|
+
onDetect: 'off' | 'reject';
|
|
1312
|
+
/** Entity kinds to screen for. Defaults to {@link DEFAULT_PII_ENTITY_TYPES}. */
|
|
1313
|
+
entities?: Array<AiPiiEntityType>;
|
|
1314
|
+
/** App-specific PII in plain language, e.g. `'internal case numbers like CASE-12345'`. */
|
|
1315
|
+
customRules?: Array<string>;
|
|
1316
|
+
/**
|
|
1317
|
+
* Model performing the screening. Defaults to {@link DEFAULT_PII_CLASSIFIER_MODEL}. Each attempt is
|
|
1318
|
+
* bounded at a minute, so an override has to answer within it.
|
|
1319
|
+
*/
|
|
1320
|
+
classifierModel?: AiChatModelSelection;
|
|
1321
|
+
/** Literal values that never count as PII, e.g. a shared support address. */
|
|
1322
|
+
allowList?: Array<string>;
|
|
1323
|
+
};
|
|
1324
|
+
/**
|
|
1325
|
+
* Outcome of screening one prompt. On a detection the prompt is replaced by {@link redactedPrompt}
|
|
1326
|
+
* everywhere it would otherwise be stored, so the audit trail records that a request was refused
|
|
1327
|
+
* and why without restating the values that caused it.
|
|
1328
|
+
* @category AI
|
|
1329
|
+
*/
|
|
1330
|
+
export type AiPiiScanResult = {
|
|
1331
|
+
detected: false;
|
|
1332
|
+
} | {
|
|
1333
|
+
detected: true;
|
|
1334
|
+
/** Entity kinds and custom-rule names that matched. Never the matched values. */
|
|
1335
|
+
matchedTypes: Array<string>;
|
|
1336
|
+
/** The prompt with every match replaced by a `[REDACTED:<type>]` placeholder. */
|
|
1337
|
+
redactedPrompt: string;
|
|
1338
|
+
};
|
|
1339
|
+
/**
|
|
1340
|
+
* Response structure for transcribing audio and asking an AI agent a question.
|
|
1341
|
+
* @category AI
|
|
1342
|
+
*/
|
|
1343
|
+
export interface AiTranscribeAndAskResponse {
|
|
1344
|
+
/** The AI agent's response to the transcribed prompt. */
|
|
1345
|
+
responseString: string;
|
|
1346
|
+
/** The transcribed text from the audio input. */
|
|
1347
|
+
transcribedPrompt: string;
|
|
1348
|
+
/** The annotations associated with the AI response, if any. */
|
|
1349
|
+
annotations?: Record<string, AiAnnotation>;
|
|
1350
|
+
}
|
|
1351
|
+
/** Per application AI settings. */
|
|
1352
|
+
export interface ApplicationAiSettings {
|
|
1353
|
+
/** Maps AI provider name to API key secret name that must be used for any request made by the application. */
|
|
1354
|
+
apiKeys: Partial<Record<AiProviderType, SecretKey>>;
|
|
1355
|
+
}
|
|
1356
|
+
/**
|
|
1357
|
+
* Options for user-provided LLM models.
|
|
1358
|
+
* @category AI
|
|
1359
|
+
*/
|
|
1360
|
+
export interface UserAiChatOptions extends BaseAiChatOptions {
|
|
1361
|
+
/** LLM Model to use for the chat query. */
|
|
1362
|
+
model: UserAiChatModelName;
|
|
1363
|
+
}
|
|
1364
|
+
/**
|
|
1365
|
+
* Response structure for asking a user LLM a question.
|
|
1366
|
+
* @category AI
|
|
1367
|
+
*/
|
|
1368
|
+
export interface UserAiAskResponse {
|
|
1369
|
+
/** The response from the AI agent. */
|
|
1370
|
+
response?: string;
|
|
1371
|
+
/** Prompt tokens used by the request, including any the prompt cache served. */
|
|
1372
|
+
inputTokens?: number;
|
|
1373
|
+
/** The number of output tokens generated by the AI agent. */
|
|
1374
|
+
outputTokens?: number;
|
|
1375
|
+
/** Cached input tokens read from the prompt cache. Only set by providers that report it (e.g. claude-code). */
|
|
1376
|
+
cacheReadInputTokens?: number;
|
|
1377
|
+
/** Input tokens written to the prompt cache. Only set by providers that report it (e.g. claude-code). */
|
|
1378
|
+
cacheWriteInputTokens?: number;
|
|
1379
|
+
/** Total request cost in USD as reported by the provider. Only set by providers that compute it (e.g. claude-code). */
|
|
1380
|
+
totalCostUsd?: number;
|
|
1381
|
+
/**
|
|
1382
|
+
* True when the run succeeded but persisting its workspace (push) failed, so the working-directory
|
|
1383
|
+
* changes made during this ask may not survive to the next one. Only ever set for workspace-backed CLI
|
|
1384
|
+
* agents; absent otherwise.
|
|
1385
|
+
*/
|
|
1386
|
+
workspacePushFailed?: boolean;
|
|
1387
|
+
}
|
|
1388
|
+
/** Represents an annotation in the AI response. */
|
|
1389
|
+
export type AiAnnotation = AiFileAnnotation;
|
|
1390
|
+
/** Represents an annotation for a file in the AI response. */
|
|
1391
|
+
export interface AiFileAnnotation {
|
|
1392
|
+
/** The type of the annotation, always 'file'. */
|
|
1393
|
+
type: 'file';
|
|
1394
|
+
/** The AI file with the URL to the file */
|
|
1395
|
+
aiFileUrl: AiFileUrl;
|
|
1396
|
+
}
|
|
1397
|
+
/**
|
|
1398
|
+
* Context for an AI session
|
|
1399
|
+
*/
|
|
1400
|
+
export type AiSessionContext = {
|
|
1401
|
+
/** The ID of the client initiating the session. */
|
|
1402
|
+
clientId: string;
|
|
1403
|
+
/** The ID of the AI agent involved in the session. */
|
|
1404
|
+
agentId: string;
|
|
1405
|
+
/** The ID of the job associated with the session. */
|
|
1406
|
+
jobId: JobId;
|
|
1407
|
+
/**
|
|
1408
|
+
* The conversation this call belongs to, as the caller named it (`memoryOptions.memoryId`).
|
|
1409
|
+
* Stable across the turns of one chat and different for two chats, including
|
|
1410
|
+
* two chats of the same client, which `clientId` is not: a client id belongs to a connection, and
|
|
1411
|
+
* one connection can carry several conversations. Not the id chat history is keyed by — that one
|
|
1412
|
+
* falls back to `clientId` — so do not read it as one. Absent for callers that named no conversation
|
|
1413
|
+
* (a direct function call, security rules).
|
|
1414
|
+
*/
|
|
1415
|
+
conversationId?: string;
|
|
1416
|
+
/**
|
|
1417
|
+
* ID of the status update that triggered this session (e.g. the agent's "Calling AI Function"
|
|
1418
|
+
* event). Status updates emitted on behalf of this session nest under it in the status feed.
|
|
1419
|
+
*/
|
|
1420
|
+
parentStatusUpdateId?: string;
|
|
1421
|
+
/**
|
|
1422
|
+
* Whether the invoking agent has audit logging enabled. Sub-agents working on behalf of this
|
|
1423
|
+
* session gate their own audit-log writes on it, keeping one job's audit trail consistent.
|
|
1424
|
+
*/
|
|
1425
|
+
auditLog?: boolean;
|
|
1426
|
+
/**
|
|
1427
|
+
* The chat timeout (in milliseconds) the root chat request explicitly set. Present only when
|
|
1428
|
+
* the root request passed `timeoutMs`. Nested AI operations (e.g. AI-query stages spawned by a
|
|
1429
|
+
* tool call) budget against it so a long-running parent chat is not silently capped by the
|
|
1430
|
+
* nested defaults; explicitly configured per-stage `aiOptions.timeoutMs` is more specific and
|
|
1431
|
+
* takes precedence over it.
|
|
1432
|
+
*/
|
|
1433
|
+
timeoutMs?: number;
|
|
1434
|
+
};
|
|
1435
|
+
/**
|
|
1436
|
+
* API request to delete an AI agent
|
|
1437
|
+
* @category AI
|
|
1438
|
+
*/
|
|
1439
|
+
export interface DeleteAgentRequest {
|
|
1440
|
+
/** The ID of the agent to delete */
|
|
1441
|
+
agentId: string;
|
|
1442
|
+
}
|
|
1443
|
+
/**
|
|
1444
|
+
* API response from agent ask methods
|
|
1445
|
+
* @category AI
|
|
1446
|
+
*/
|
|
1447
|
+
export interface AiAskResponse {
|
|
1448
|
+
/** The response string from the agent */
|
|
1449
|
+
responseString: string;
|
|
1450
|
+
/** Optional annotations (e.g., file references) in the response */
|
|
1451
|
+
annotations?: Record<string, AiAnnotation>;
|
|
1452
|
+
/** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
|
|
1453
|
+
routing?: AiModelRoutingResult;
|
|
1454
|
+
}
|
|
1455
|
+
/**
|
|
1456
|
+
* API request to create speech from text
|
|
1457
|
+
* @category AI
|
|
1458
|
+
*/
|
|
1459
|
+
export interface AiAudioCreateSpeechRequest {
|
|
1460
|
+
/** The text input to convert to speech */
|
|
1461
|
+
input: string;
|
|
1462
|
+
/** Options for speech generation */
|
|
1463
|
+
options: AiAudioCreateSpeechOptions;
|
|
1464
|
+
}
|
|
1465
|
+
/**
|
|
1466
|
+
* API request to generate an image
|
|
1467
|
+
* @category AI
|
|
1468
|
+
*/
|
|
1469
|
+
export interface AiGenerateImageRequest {
|
|
1470
|
+
/** The prompt describing the image to generate */
|
|
1471
|
+
prompt: string;
|
|
1472
|
+
/** Options for image generation */
|
|
1473
|
+
options?: AiGenerateImageOptions;
|
|
1474
|
+
}
|
|
1475
|
+
/**
|
|
1476
|
+
* Revision action types for agent history tracking.
|
|
1477
|
+
* @category AI
|
|
1478
|
+
*/
|
|
1479
|
+
export type AiAgentRevisionAction = 'created' | 'updated' | 'deleted';
|
|
1480
|
+
/**
|
|
1481
|
+
* Represents a single agent revision entry.
|
|
1482
|
+
* @category AI
|
|
1483
|
+
*/
|
|
1484
|
+
export interface AiAgentRevision {
|
|
1485
|
+
/** The ID of the agent this revision belongs to. */
|
|
1486
|
+
agentId: AiAgentId;
|
|
1487
|
+
/** The revision number, incremented for each change to the agent. */
|
|
1488
|
+
revisionNumber: number;
|
|
1489
|
+
/** The action that triggered this revision (created, updated, or deleted). */
|
|
1490
|
+
action: AiAgentRevisionAction;
|
|
1491
|
+
/** Timestamp when this revision was created. */
|
|
1492
|
+
createdAt: Date;
|
|
1493
|
+
/** Snapshot of the agent data at the time of the revision. */
|
|
1494
|
+
agentSnapshot: AiAgent;
|
|
1495
|
+
}
|
|
1496
|
+
/**
|
|
1497
|
+
* Request to list all revisions for an agent.
|
|
1498
|
+
* @category AI
|
|
1499
|
+
*/
|
|
1500
|
+
export interface ListAgentRevisionsRequest {
|
|
1501
|
+
/** The ID of the agent to list revisions for. */
|
|
1502
|
+
agentId: AiAgentId;
|
|
1503
|
+
}
|
|
1504
|
+
/**
|
|
1505
|
+
* Response containing the list of agent revisions.
|
|
1506
|
+
* @category AI
|
|
1507
|
+
*/
|
|
1508
|
+
export interface ListAgentRevisionsResponse {
|
|
1509
|
+
/** The list of revisions for the agent, sorted by revision number descending. */
|
|
1510
|
+
revisions: Array<AiAgentRevision>;
|
|
1511
|
+
}
|
|
1512
|
+
/**
|
|
1513
|
+
* Request to get a specific agent revision.
|
|
1514
|
+
* @category AI
|
|
1515
|
+
*/
|
|
1516
|
+
export interface GetAgentRevisionRequest {
|
|
1517
|
+
/** The ID of the agent to get the revision for. */
|
|
1518
|
+
agentId: AiAgentId;
|
|
1519
|
+
/** The revision number to retrieve. */
|
|
1520
|
+
revisionNumber: number;
|
|
1521
|
+
}
|
|
1522
|
+
/**
|
|
1523
|
+
* Response containing a specific agent revision.
|
|
1524
|
+
* @category AI
|
|
1525
|
+
*/
|
|
1526
|
+
export interface GetAgentRevisionResponse {
|
|
1527
|
+
/** The requested revision, or undefined if not found. */
|
|
1528
|
+
revision: AiAgentRevision | undefined;
|
|
1529
|
+
}
|
|
1530
|
+
/**
|
|
1531
|
+
* Request to restore an agent to a specific revision.
|
|
1532
|
+
* @category AI
|
|
1533
|
+
*/
|
|
1534
|
+
export interface RestoreAgentRevisionRequest {
|
|
1535
|
+
/** The ID of the agent to restore. */
|
|
1536
|
+
agentId: AiAgentId;
|
|
1537
|
+
/** The revision number to restore the agent to. */
|
|
1538
|
+
revisionNumber: number;
|
|
1539
|
+
}
|
|
1540
|
+
/**
|
|
1541
|
+
* Request to delete a specific agent revision.
|
|
1542
|
+
* @category AI
|
|
1543
|
+
*/
|
|
1544
|
+
export interface DeleteAgentRevisionRequest {
|
|
1545
|
+
/** The ID of the agent whose revision should be deleted. */
|
|
1546
|
+
agentId: AiAgentId;
|
|
1547
|
+
/** The revision number to delete. */
|
|
1548
|
+
revisionNumber: number;
|
|
1549
|
+
}
|
|
1550
|
+
/**
|
|
1551
|
+
* Options for the agent builder.
|
|
1552
|
+
* @category AI
|
|
1553
|
+
*/
|
|
1554
|
+
export interface BuildAgentOptions {
|
|
1555
|
+
/** Whether the caller has permission to create or update integrations. Defaults to false. */
|
|
1556
|
+
canManageIntegrations?: boolean;
|
|
1557
|
+
}
|
|
1558
|
+
/**
|
|
1559
|
+
* Response containing the list of AI agents in an application.
|
|
1560
|
+
* @category AI
|
|
1561
|
+
*/
|
|
1562
|
+
export interface ListAgentsResponse {
|
|
1563
|
+
/** All AI agents defined for the application. */
|
|
1564
|
+
agents: Array<AiAgent>;
|
|
1565
|
+
}
|
|
1566
|
+
/**
|
|
1567
|
+
* Request options for listing the chat models available to an application.
|
|
1568
|
+
* @category AI
|
|
1569
|
+
*/
|
|
1570
|
+
export interface ListChatModelsRequest {
|
|
1571
|
+
/**
|
|
1572
|
+
* When true, deprecated vendor models (those with `replacedBy`) are included.
|
|
1573
|
+
* Defaults to false (only active models are returned).
|
|
1574
|
+
*/
|
|
1575
|
+
includeDeprecated?: boolean;
|
|
1576
|
+
}
|
|
1577
|
+
/**
|
|
1578
|
+
* Response containing the list of chat models available to an application.
|
|
1579
|
+
* Includes both Squid-provided vendor models and any custom integration models.
|
|
1580
|
+
* Vendor models carry a human-readable `description`. Deprecated vendor models are
|
|
1581
|
+
* included only when requested via `includeDeprecated` and are marked with `replacedBy`.
|
|
1582
|
+
* @category AI
|
|
1583
|
+
*/
|
|
1584
|
+
export interface ListChatModelsResponse {
|
|
1585
|
+
/** All chat models available to the application. */
|
|
1586
|
+
models: Array<ModelIdSpec>;
|
|
1587
|
+
}
|
|
1588
|
+
/**
|
|
1589
|
+
* Request options for listing the embedding models a new knowledge base can be created on.
|
|
1590
|
+
* @category AI
|
|
1591
|
+
*/
|
|
1592
|
+
export interface ListEmbeddingModelsRequest {
|
|
1593
|
+
/**
|
|
1594
|
+
* When true, deprecated vendor models (those with `replacedBy`) are included.
|
|
1595
|
+
* Defaults to false (only active models are returned).
|
|
1596
|
+
*/
|
|
1597
|
+
includeDeprecated?: boolean;
|
|
1598
|
+
}
|
|
1599
|
+
/**
|
|
1600
|
+
* Response containing the embedding models a new knowledge base can be created on: Squid-provided
|
|
1601
|
+
* vendor models and the application's custom integration models. Exactly one entry carries `isDefault`.
|
|
1602
|
+
* Deprecated vendor models are included only when requested via `includeDeprecated` and are marked
|
|
1603
|
+
* with `replacedBy`; an existing knowledge base keeps its model regardless.
|
|
1604
|
+
* @category AI
|
|
1605
|
+
*/
|
|
1606
|
+
export interface ListEmbeddingModelsResponse {
|
|
1607
|
+
/** All embedding models available to the application. */
|
|
1608
|
+
models: Array<EmbeddingModelIdSpec>;
|
|
1609
|
+
}
|