@squidcloud/cli 1.0.445 → 1.0.447

package/dist/resources/claude/skills/squid-development/reference/ai.md

@@ -0,0 +1,773 @@
+# AI Features
+
+Squid provides comprehensive AI capabilities including agents, knowledge bases, image/audio processing, and AI-powered queries.
+
+**REST API:** Most AI features are also available via REST API. See [api.md](api.md) or https://docs.getsquid.ai/reference-docs/api/
+
+## Contents
+- Supported Models
+- AI Agents
+- Knowledge Bases
+- AI Files
+- Image & Audio
+- AI Query & API Call
+- Application Settings
+- Backend Decorators
+- MCP (Model Context Protocol)
+- LLM Services
+- AI Functions Configurator
+
+## Supported Models
+
+Squid supports multiple AI providers and models. The available models are defined as TypeScript constants:
+
+```typescript
+import {
+  // Chat model constants (by provider)
+  OPENAI_CHAT_MODEL_NAMES,
+  ANTHROPIC_CHAT_MODEL_NAMES,
+  GEMINI_CHAT_MODEL_NAMES,
+  GROK_CHAT_MODEL_NAMES,
+  VENDOR_AI_CHAT_MODEL_NAMES,  // All chat models combined
+
+  // Embedding model constants
+  AI_EMBEDDINGS_MODEL_NAMES,
+  OPENAI_EMBEDDINGS_MODEL_NAMES,
+  VOYAGE_EMBEDDING_MODEL_NAMES,
+
+  // Image generation model constants
+  AI_IMAGE_MODEL_NAMES,
+  OPENAI_IMAGE_MODEL_NAMES,
+  STABLE_DIFFUSION_MODEL_NAMES,
+  FLUX_MODEL_NAMES,
+
+  // Audio model constants
+  AI_AUDIO_TRANSCRIPTION_MODEL_NAMES,
+  OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES,
+
+  // Type definitions
+  AiChatModelName,
+  AiEmbeddingsModelName,
+  AiImageModelName,
+  AiAudioTranscriptionModelName,
+  AiAudioCreateSpeechModelName,
+} from '@squidcloud/client';
+```
+
+**Model Categories:**
+- **Chat Models**: Used for AI Agents, AI Query, etc. (OpenAI, Anthropic, Gemini, Grok)
+- **Embedding Models**: Used for Knowledge Bases (OpenAI, Voyage)
+- **Image Generation Models**: Used for image creation (DALL-E, Stable Diffusion, Flux)
+- **Audio Models**: Transcription (Whisper, GPT-4o) and Text-to-Speech (TTS-1, GPT-4o-mini-tts)
+
+## AI Agents
+
+AI Agents are powerful, configurable AI assistants that can interact with your data, call functions, connect to integrations, and collaborate with other agents.
+
+REST API: [Agent API](https://docs.getsquid.ai/reference-docs/api/#tag/Agent) | OpenAI-specific features: [openai.md](openai.md)
+
+### Agent Capabilities
+
+An AI Agent can:
+- Maintain conversation history (**memory is enabled by default**)
+- Call backend functions decorated with `@aiFunction`
+- Query databases and APIs through connected integrations
+- Search knowledge bases for relevant information
+- Collaborate with other AI agents
+- Process voice input and generate voice output
+- Accept files as part of chat requests
+
+### Creating and Managing Agents
+
+```typescript
+const aiClient = squid.ai();
+
+// Get the built-in agent (no ID required)
+const builtInAgent = aiClient.agent();
+
+// Get a custom agent by ID
+const myAgent = aiClient.agent('my-agent-id');
+
+// Get an agent with an Agent API key (allows calling without App API key, bypasses @secureAiAgent methods)
+const agentWithKey = aiClient.agent('my-agent-id', {
+  apiKey: 'your-agent-api-key'
+});
+
+// Create or update an agent
+await myAgent.upsert({
+  description: 'Customer support assistant',
+  isPublic: false,  // Whether the agent is publicly accessible
+  auditLog: true,   // Enable audit logging for compliance
+  options: {
+    model: 'gpt-5-mini', // or 'claude-sonnet-4-5-20250929', 'gemini-3-flash'
+    instructions: 'You are a helpful customer support assistant. Be concise and professional.',
+    temperature: 0.7
+  }
+});
+
+// Get agent details
+const agentInfo = await myAgent.get();
+console.log(agentInfo.id, agentInfo.description, agentInfo.options.model);
+
+// Update specific properties
+await myAgent.updateInstructions('You are a technical support specialist.');
+await myAgent.updateModel('claude-sonnet-4-5-20250929');
+await myAgent.updateGuardrails(['no-harmful-content']);
+
+// Delete an agent
+await myAgent.delete();
+
+// List all agents
+const agents = await squid.ai().listAgents();
+agents.forEach(agent => console.log(`${agent.id}: ${agent.description}`));
+
+// Manage agent API keys
+const apiKey = await myAgent.regenerateApiKey();
+console.log('New API key:', apiKey);
+
+const existingKey = await myAgent.getApiKey();
+console.log('Current API key:', existingKey);
+
+// Update agent options at specific path
+await myAgent.setAgentOptionInPath('temperature', 0.9);
+await myAgent.setAgentOptionInPath('options.maxTokens', 2000);
+
+// Update connected agents
+await myAgent.updateConnectedAgents([
+  { agentId: 'helper-agent', description: 'Helps with tasks' }
+]);
+
+// Update or delete custom guardrails
+await myAgent.updateCustomGuardrails('Never reveal sensitive information');
+await myAgent.deleteCustomGuardrail();
+```
+
+### Agent Lifecycle
+
+1. **Creation** - Use `upsert()` to create a new agent with an ID
+2. **Active** - Agent can process requests
+3. **Update** - Use `upsert()` or specific update methods
+4. **Deletion** - Use `delete()` to permanently remove the agent
+
+**Important Notes:**
+- Agent IDs are permanent - once created, you cannot change the ID
+- Deleting an agent does not delete associated chat history
+- The built-in agent (accessed via `agent()` with no ID) cannot be deleted
+- **Agent API Keys**: You can pass an options object with an `apiKey` when calling `agent()`:
+  - Allows calling agent methods without requiring an App API key
+  - Bypasses any `@secureAiAgent` security methods when calling agent ask functions
+  - Useful for direct agent access without app-level authentication
+
+### Connecting Resources to Agents
+
+Agents become powerful when connected to resources:
+- **Other AI agents** (`connectedAgents`) - Agent collaboration
+- **Backend functions** (`functions`) - Custom logic via `@aiFunction` decorators
+- **Integrations** (`connectedIntegrations`) - Database/API queries
+- **Knowledge bases** (`connectedKnowledgeBases`) - RAG (Retrieval Augmented Generation)
+
+#### Connected Agents
+
+Allow one agent to call another agent as a specialized sub-task handler.
+
+```typescript
+const response = await agent.ask('Analyze our sales data and send report to team', {
+  connectedAgents: [
+    {
+      agentId: 'data-analyst-agent',
+      description: 'Analyzes sales data and generates reports'
+    },
+    {
+      agentId: 'email-sender-agent',
+      description: 'Sends emails to team members'
+    }
+  ]
+});
+```
+
+#### Functions
+
+Connect backend functions decorated with `@aiFunction` that the agent can call.
+
+```typescript
+// Backend function
+@aiFunction('Gets current inventory for a product', [
+  { name: 'productId', type: 'string', required: true, description: 'Product ID' }
+])
+async getInventory({ productId }: { productId: string }): Promise<number> {
+  return await db.inventory.get(productId);
+}
+
+// Client - Agent uses the function
+const response = await agent.ask('How many units of product-123 do we have?', {
+  functions: ['getInventory'] // Function name or ID
+});
+
+// With predefined parameters (hidden from AI)
+const response = await agent.ask('Send notification', {
+  functions: [
+    {
+      functionId: 'sendEmail',
+      context: { apiKey: 'secret-key' } // Passed to function but hidden from AI
+    }
+  ]
+});
+```
+
+#### Connected Integrations
+
+Connect database or API integrations so the agent can query them directly.
+
+```typescript
+const response = await agent.ask('Show me active users from last week', {
+  connectedIntegrations: [
+    {
+      integrationId: 'postgres-db',
+      integrationType: 'database',
+      description: 'Main application database with users, orders, and products',
+      instructions: 'Only query the users table unless explicitly asked otherwise',
+      options: {
+        // Integration-specific options
+      }
+    },
+    {
+      integrationId: 'stripe-api',
+      integrationType: 'api',
+      description: 'Stripe payment API for retrieving payment information'
+    }
+  ]
+});
+```
+
+#### Connected Knowledge Bases
+
+Connect knowledge bases for RAG - agent retrieves relevant context before answering.
+
+```typescript
+const response = await agent.ask('What is our return policy?', {
+  connectedKnowledgeBases: [
+    {
+      knowledgeBaseId: 'company-policies-kb',
+      description: 'Use this when asked about company policies, procedures, or guidelines'
+    },
+    {
+      knowledgeBaseId: 'product-docs-kb',
+      description: 'Use this when asked about product features, specifications, or usage'
+    }
+  ]
+});
+```
+
+### Agent Chat Methods
+
+```typescript
+const agent = squid.ai().agent('my-agent');
+
+// Chat (streaming) - Returns RxJS Observable
+// IMPORTANT: Streaming behavior:
+// - NO connected resources: streams token-by-token
+// - HAS connected resources: emits ONCE with complete response
+const chatObs = agent.chat('What is your return policy?', {
+  // Memory management
+  memoryOptions: {
+    memoryMode: 'read-write', // 'none' | 'read-only' | 'read-write'
+    memoryId: 'user-123',     // Unique per user/session
+    expirationMinutes: 1440   // 24 hours
+  },
+
+  // Connected resources (can also be set on agent.upsert)
+  connectedAgents: [{ agentId: 'specialist-agent', description: 'Handles X' }],
+  functions: ['function1', 'function2'],
+  connectedIntegrations: [{ integrationId: 'db', integrationType: 'database', description: '...' }],
+  connectedKnowledgeBases: [{ knowledgeBaseId: 'kb1', description: 'When to use this KB' }],
+
+  // Model & generation
+  model: 'gpt-5-mini', // Override agent's default model
+  temperature: 0.7,
+  maxTokens: 4000,
+  maxOutputTokens: 2000,
+  instructions: 'Additional instructions for this request only',
+  responseFormat: 'json_object', // or 'text'
+  verbosity: 'medium', // 'low' | 'medium' | 'high' (OpenAI only)
+  reasoningEffort: 'high', // 'minimal' | 'low' | 'medium' | 'high' (for reasoning models)
+
+  // Context & RAG
+  disableContext: false,
+  enablePromptRewriteForRag: false,
+  includeReference: false,
+  contextMetadataFilterForKnowledgeBase: {
+    'kb-id': { category: 'documentation' }
+  },
+
+  // Guardrails & quotas
+  guardrails: ['no-harmful-content', 'no-pii'],
+  quotas: {
+    maxAiCallStackSize: 5
+  },
+
+  // Files & voice
+  fileUrls: [
+    { id: 'file1', type: 'image', purpose: 'context', url: 'https://...', description: 'Product image' }
+  ],
+  voiceOptions: {
+    modelName: 'tts-1',
+    voice: 'alloy', // alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse
+    speed: 1.0
+  },
+
+  // Advanced
+  smoothTyping: true,
+  useCodeInterpreter: 'llm', // 'none' | 'llm' (OpenAI/Gemini only)
+  executionPlanOptions: {
+    enabled: true,
+    model: 'gpt-5-mini',
+    reasoningEffort: 'high',
+    allowClarificationQuestions: false
+  },
+  agentContext: { userId: '123', role: 'admin' },
+  includeMetadata: false
+});
+
+chatObs.subscribe(text => {
+  console.log(text);
+});
+
+// Ask (complete response - same options as chat)
+const response = await agent.ask('Question?', { /* same options */ });
+
+// Ask with annotations (includes file references, citations)
+const result = await agent.askWithAnnotations('Question?', { /* same options */ });
+console.log(result.responseString);
+console.log(result.annotations);
+
+// Ask asynchronously (doesn't wait for response, uses job system)
+await agent.askAsync('Long running task', 'job-id-123', { /* same options */ });
+// Check job status later with squid.job().getJob('job-id-123')
+
+// Voice responses
+const voiceResult = await agent.askWithVoiceResponse('Hello', {
+  voiceOptions: { modelName: 'tts-1', voice: 'alloy', speed: 1.0 }
+});
+console.log(voiceResult.responseString);
+console.log(voiceResult.voiceResponseFile);
+
+// Transcribe audio and chat
+const transcribeResult = await agent.transcribeAndChat(audioFile);
+console.log(transcribeResult.transcribedPrompt);
+transcribeResult.responseStream.subscribe(text => console.log(text));
+
+// Transcribe audio and ask (non-streaming)
+const askResult = await agent.transcribeAndAsk(audioFile, { /* ask options */ });
+console.log(askResult.transcribedPrompt);
+console.log(askResult.response);
+
+// Transcribe audio and get voice response
+const voiceResponse = await agent.transcribeAndAskWithVoiceResponse(audioFile, {
+  voiceOptions: { modelName: 'tts-1', voice: 'alloy' }
+});
+console.log(voiceResponse.transcribedPrompt);
+console.log(voiceResponse.responseString);
+console.log(voiceResponse.voiceResponseFile);
+
+// Get chat history
+const history = await agent.getChatHistory('memory-id-123');
+
+// Provide feedback on responses
+await agent.provideFeedback('Great response! Very helpful.');
+
+// Observe status updates (for long-running operations)
+agent.observeStatusUpdates().subscribe(status => {
+  console.log(status.title, status.tags);
+});
+```
+
+## Knowledge Bases
+
+Knowledge bases store and index documents for RAG. REST API: [KnowledgeBase API](https://docs.getsquid.ai/reference-docs/api/#tag/KnowledgeBase)
+
+```typescript
+const kb = squid.ai().knowledgeBase('product-docs');
+
+// Get knowledge base details
+const kbDetails = await kb.getKnowledgeBase();
+console.log(kbDetails);
+
+// Create or update knowledge base
+await kb.upsertKnowledgeBase({
+  description: 'Product documentation knowledge base',
+  // ...other options
+});
+
+// Delete knowledge base
+await kb.delete();
+
+// List all knowledge bases
+const allKBs = await squid.ai().listKnowledgeBases();
+
+// Upsert context (with or without file)
+await kb.upsertContext({
+  contextId: 'doc-123',
+  text: 'Product documentation...',
+  metadata: { category: 'user-guide', version: '2.0' }
+}, optionalFile);
+
+// Batch upsert
+await kb.upsertContexts([
+  { contextId: 'doc-1', text: '...' },
+  { contextId: 'doc-2', text: '...' }
+], optionalFiles);
+
+// Search with prompt
+const results = await kb.searchContextsWithPrompt({
+  prompt: 'How do I reset password?',
+  limit: 5,
+  metadata: { category: 'user-guide' }
+});
+
+// Search by context ID
+const related = await kb.searchContextsWithContextId({
+  contextId: 'doc-123',
+  limit: 10
+});
+
+// Semantic search (returns chunks)
+const searchResults = await kb.search({
+  prompt: 'authentication',
+  limit: 10
+});
+
+// Get context
+const context = await kb.getContext('doc-123');
+
+// List contexts
+const allContexts = await kb.listContexts(1000); // truncateTextAfter
+const contextIds = await kb.listContextIds();
+
+// Download context
+const download = await kb.downloadContext('doc-123');
+
+// Delete contexts
+await kb.deleteContext('doc-123');
+await kb.deleteContexts(['doc-1', 'doc-2']);
+```
+
+## AI Files
+
+Manage files stored with AI providers (OpenAI, etc.) for use with agents.
+
+```typescript
+const aiFiles = squid.ai().files('openai'); // provider: 'openai' | 'anthropic' | etc.
+
+// Upload file to AI provider
+const fileId = await aiFiles.uploadFile({
+  file: myFile, // Browser File object
+  purpose: 'assistants'
+});
+console.log('Uploaded file ID:', fileId);
+
+// Delete file from AI provider
+const deleted = await aiFiles.deleteFile(fileId);
+console.log('File deleted:', deleted);
+```
+
+## Image & Audio
+
+REST API: [AI Image API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Image), [AI Audio API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Audio) | OpenAI-specific: [openai.md](openai.md)
+
+### Image Generation
+
+```typescript
+// Generate image
+const imageUrl = await squid.ai().image().generate(
+  'A futuristic city',
+  { size: '1024x1024', quality: 'hd' }
+);
+
+// Remove background
+const noBgBase64 = await squid.ai().image().removeBackground(imageFile);
+```
+
+### Audio Processing
+
+```typescript
+// Transcribe audio
+const text = await squid.ai().audio().transcribe(audioFile, {
+  language: 'en'
+});
+
+// Text-to-speech
+const audioFile = await squid.ai().audio().createSpeech(
+  'Hello world',
+  { modelName: 'tts-1', voice: 'alloy', speed: 1.0 }
+);
+```
+
+## AI Query & API Call
+
+AI Query allows you to query your database using natural language prompts. REST API: [Database API](https://docs.getsquid.ai/reference-docs/api/#tag/Database)
+
+```typescript
+// Natural language database query (basic)
+const result = await squid.ai().executeAiQuery(
+  'built_in_db',
+  'Show me all active users who registered last month'
+);
+
+// With options
+const result = await squid.ai().executeAiQuery(
+  'built_in_db',
+  'Show me all active users who registered last month',
+  {
+    instructions: 'Only query the users collection',
+    enableRawResults: true,
+    selectCollectionsOptions: {
+      collectionsToUse: ['users']
+    },
+    generateQueryOptions: {
+      maxErrorCorrections: 3
+    },
+    analyzeResultsOptions: {
+      enableCodeInterpreter: true
+    }
+  }
+);
+
+// AI-powered API call
+const apiResult = await squid.ai().executeAiApiCall(
+  'stripe-api',
+  'Create a $50 charge for customer cus_123',
+  ['create-charge'], // allowed endpoints
+  true // provide explanation
+);
+```
+
+## Application Settings
+
+Manage AI provider settings and API keys for your application.
+
+```typescript
+const aiClient = squid.ai();
+
+// Get application AI settings
+const settings = await aiClient.getApplicationAiSettings();
+
+// Set application AI settings
+await aiClient.setApplicationAiSettings({
+  defaultModel: 'gpt-5-mini',
+  // ... other settings
+});
+
+// Set AI provider API key secret
+await aiClient.setAiProviderApiKeySecret(
+  'openai', // providerType
+  'OPENAI_API_KEY' // secret key name
+);
+```
+
+## Backend Decorators
+
+### @aiFunction
+
+Exposes function to AI agents. Agents automatically call these functions based on user prompts.
+
+```typescript
+// Simple form: description and params array
+@aiFunction('Returns the names of the pirates crew on a given ship name', [
+  { name: 'shipName', type: 'string', required: true, description: 'The name of the ship' }
+])
+async getShipCrew({ shipName }: { shipName: string }): Promise<string[]> {
+  const crew = await getCrew(shipName);
+  return crew.map(m => m.name);
+}
+
+// Options object form with more control
+@aiFunction({
+  id: 'custom-function-id',
+  description: 'Get user profile',
+  params: [
+    { name: 'userId', type: 'string', required: true, description: 'User ID' }
+  ],
+  attributes: {
+    integrationType: ['salesforce']
+  }
+})
+async getUserProfile(
+  params: { userId: string },
+  context: AiFunctionCallContext
+): Promise<User> {
+  console.log('Agent ID:', context.agentId);
+  console.log('Agent context:', context.agentContext);
+  console.log('Function context:', context.functionContext);
+  return { userId: params.userId, name: 'John' };
+}
+
+// Parameter types: 'string' | 'number' | 'boolean' | 'date' | 'files'
+@aiFunction('Books a hotel room', [
+  { name: 'hotelName', type: 'string', required: true, description: 'Name of hotel' },
+  { name: 'checkInDate', type: 'date', required: true, description: 'Check-in date' },
+  { name: 'numberOfGuests', type: 'number', required: true, description: 'Number of guests' },
+  { name: 'breakfast', type: 'boolean', required: false, description: 'Include breakfast' },
+  { name: 'roomType', type: 'string', required: true, description: 'Type of room',
+    enum: ['single', 'double', 'suite'] }
+])
+async bookHotel(args: BookingArgs): Promise<string> {
+  return `Booked ${args.roomType} room at ${args.hotelName}`;
+}
+```
+
+### AI Security Decorators
+
+For `@secureAiAgent` and `@secureAiQuery`, see [security.md](security.md#ai-security).
+
+## MCP (Model Context Protocol)
+
+Squid supports MCP for extending agent capabilities.
+
+### @mcpServer
+
+Define an MCP server that agents can connect to. The decorator is a class decorator.
+
+```typescript
+@mcpServer({
+  id: 'my-mcp-server',
+  name: 'My MCP Server',
+  description: 'A server that provides custom tools',
+  version: '1.0.0'
+})
+export class MyMcpServer extends SquidService {
+  // MCP tools defined here
+}
+```
+
+**McpServerOptions:**
+- `id` (string): Unique ID for this MCP server (used in MCP URL)
+- `name` (string): The MCP name exposed in the manifest
+- `description` (string): Description of the MCP server
+- `version` (string): Version of the MCP server
+
+### @mcpTool
+
+Define tools that MCP-connected agents can use. Takes an options object with description and inputSchema (JSON Schema).
+
+```typescript
+@mcpTool({
+  description: 'Searches the database for records matching the query',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+      limit: { type: 'number', description: 'Max results to return' }
+    },
+    required: ['query']
+  }
+})
+async searchDatabase({ query, limit = 10 }: { query: string; limit?: number }): Promise<SearchResults> {
+  return await this.squid.collection('records')
+    .query()
+    .like('content', `%${query}%`)
+    .limit(limit)
+    .snapshot();
+}
+```
+
+**McpToolMetadataOptions:**
+- `description` (string): Describes the tool's capabilities (used by AI to determine when to call it)
+- `inputSchema` (JSONSchema): Parameters for the MCP tool
+- `outputSchema?` (JSONSchema): Optional output schema
+
+### @mcpAuthorizer
+
+Authorize MCP connections. This decorator takes no arguments and is applied within an MCP server class.
+
+```typescript
+@mcpAuthorizer()
+authorizeMcp(): boolean {
+  return this.isAuthenticated();
+}
+```
+
+## LLM Services
+
+For custom LLM integrations. LLM services allow you to integrate custom AI models with Squid's AI infrastructure.
+
+### @llmService
+
+Define a custom LLM service. This is a class decorator that registers custom AI models.
+
+```typescript
+import { llmService, llmAsk, SquidLlmService } from '@squidcloud/backend';
+
+const MY_MODELS = {
+  'my-model-v1': { displayName: 'My Model v1', maxTokens: 4096 },
+  'my-model-v2': { displayName: 'My Model v2', maxTokens: 8192 }
+};
+
+@llmService({ models: MY_MODELS, supportsFunctions: true })
+export class CustomLlmService extends SquidLlmService {
+  @llmAsk()
+  async ask(prompt: string): Promise<string> {
+    // Custom LLM implementation
+    const response = await callMyCustomLlm(prompt);
+    return response;
+  }
+}
+```
+
+**LlmServiceOptions:**
+- `models` (Record<string, ModelMetadata>): Map of model names to their metadata
+- `supportsFunctions?` (boolean): Whether the LLM supports function calling
+
+**Note:** Custom LLM services extend `SquidLlmService`, not `SquidService`.
+
+## AI Functions Configurator
+
+Configure which AI functions are available to agents for specific integration types. This allows you to override or exclude functions and set predefined parameters.
+
+```typescript
+import { aiFunctionsConfigurator, AiFunctionsConfiguratorRequest, AiFunctionsConfiguratorResponse } from '@squidcloud/backend';
+
+@aiFunctionsConfigurator({ integrationTypes: ['salesforce', 'hubspot'] })
+configureAiFunctions(request: AiFunctionsConfiguratorRequest): AiFunctionsConfiguratorResponse {
+  console.log('Integration ID:', request.integrationId);
+  console.log('Integration type:', request.integrationType);
+
+  return {
+    functionOverrides: {
+      'getInventory': {
+        id: 'getInventory',
+        isExcluded: false,
+        predefinedParameters: { region: 'us-west-2' }
+      },
+      'processPayment': {
+        id: 'processPayment',
+        isExcluded: !this.isAuthenticated(),
+        predefinedParameters: {}
+      }
+    }
+  };
+}
+```
+
+**AiFunctionsConfiguratorMetadataOptions:**
+- `id?` (string): Unique configurator ID (defaults to function name)
+- `integrationTypes` (IntegrationType[]): Integration types this configurator applies to
+
+**AiFunctionsConfiguratorRequest:**
+- `integrationId`: ID of the connected integration
+- `integrationType`: Type of the integration
+- `metadata`: Current connected integration metadata
+
+**AiFunctionsConfiguratorResponse:**
+- `functionOverrides`: Map of function ID to override details
+  - `id`: Function ID
+  - `isExcluded?`: If true, function won't be available
+  - `predefinedParameters`: Parameters to fill with predefined values
+
+## Best Practices
+
+1. **Use memoryOptions for AI conversations** - Not deprecated chatId
+2. **Agent IDs are permanent** - Plan naming carefully, cannot be changed after creation
+3. **Memory is enabled by default** - Set `memoryMode: 'none'` to disable conversation history
+4. **Streaming behavior differs with connected resources** - No resources: streams token-by-token; Has resources: emits once with complete response
+5. **Deleting an agent doesn't delete chat history** - History persists independently
+6. **Custom LLM services extend SquidLlmService** - Not SquidService