@squidcloud/client

import { Observable } from 'rxjs'; import { AiAgent, AiChatMessage, AiChatModelSelection, AiConnectedAgentMetadata, AiConnectedIntegrationMetadata, AiConnectedKnowledgeBaseMetadata, AiStatusMessage, AiTranscribeAndAskResponse, AllAiAgentChatOptions, BuildAgentOptions, GuardrailsOptions, ListAgentRevisionsResponse, UpsertAgentRequest } from '../../../internal-common/src/public-types/ai-agent.public-types'; import { JobId } from '../../../internal-common/src/public-types/job.public-types'; import { Paths } from '../../../internal-common/src/public-types/typescript.public-types'; import { AiAskOptions, AiAskOptionsWithVoice, AiChatOptionsWithoutVoice, AskResponse, AskWithVoiceResponse, TranscribeAndAskWithVoiceResponse, TranscribeAndChatResponse } from './ai-agent-client.types'; /** * Parameters for creating or updating an AI agent. * Excludes the `id` field, as it is derived from the agent instance. * @category AI */ export type UpsertAgentRequestParams = Omit<UpsertAgentRequest, 'id'>; /** * AiAgentReference provides methods for managing AI agents, including * retrieving, updating, and deleting agents, handling agent contexts, * and interacting with chat or voice-based AI functionalities. * @category AI */ export declare class AiAgentReference { private readonly agentId; private readonly agentApiKey; private readonly ongoingChatSequences; private readonly rpcManager; private readonly socketManager; private readonly jobClient; private readonly backendFunctionManager; private readonly getMetricAnnotations; /** * Retrieves metadata and configuration of the AI agent. */ get(): Promise<AiAgent | undefined>; /** * Creates or updates the AI agent with the provided parameters. */ upsert(agent: UpsertAgentRequestParams): Promise<void>; /** * Deletes the AI agent. Does not fail if the agent does not exist. */ delete(): Promise<void>; /** * Updates the agent's instruction prompt. */ updateInstructions(instructions: string): Promise<void>; /** * Changes the AI model used by the agent. */ updateModel(model: AiChatModelSelection): Promise<void>; /** * Updates the list of agents connected to this agent. */ updateConnectedAgents(connectedAgents: Array<AiConnectedAgentMetadata>): Promise<void>; /** * Updates the agent's guardrails with the provided options. */ updateGuardrails(guardrails: GuardrailsOptions): Promise<void>; /** * Updates the agent's custom guardrails with the provided custom guardrail. */ updateCustomGuardrails(customGuardrail: string): Promise<void>; /** * Deletes the custom guardrails for the agent. */ deleteCustomGuardrail(): Promise<void>; /** * Regenerates the api key for the agent. * Will throw an error if the agent does not exist. * * @returns the new api key */ regenerateApiKey(): Promise<string>; /** * Fetches the default api key for the agent * @returns the api key if one exists */ getApiKey(): Promise<string | undefined>; /** * Lists all revisions (history) of the agent. * @returns the list of revisions sorted by newest first */ listRevisions(): Promise<ListAgentRevisionsResponse>; /** * Restores the agent to a previous revision. * This will create a new revision with the current state before restoring. * @param revisionNumber The revision number to restore to */ restoreRevision(revisionNumber: number): Promise<void>; /** * Deletes a specific revision. * @param revisionNumber The revision number to delete */ deleteRevision(revisionNumber: number): Promise<void>; /** * Sends a prompt to the agent and receives streamed text responses. * @param prompt The text prompt to send to the agent. * @param options Optional parameters for the AI ask request. * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who * knows it can look up the job’s status. */ chat<T extends AiChatModelSelection | undefined>(prompt: string, options?: AiChatOptionsWithoutVoice<T>, jobId?: JobId): Observable<string>; /** * Transcribes the given file and performs a chat interaction. * @param fileToTranscribe The audio file to transcribe and send to the agent. * @param options Optional parameters for the AI ask request. * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who * knows it can look up the job’s status. */ transcribeAndChat(fileToTranscribe: File, options?: AiChatOptionsWithoutVoice, jobId?: JobId): Promise<TranscribeAndChatResponse>; /** * Sends a prompt and returns a full string response. * @param prompt The text prompt to send to the agent. * @param options Optional parameters for the AI ask request. * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who * knows it can look up the job’s status. */ ask<T extends AiChatModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<string>; /** * Sends a prompt and returns the string response and file annotations. * @param prompt The text prompt to send to the agent. * @param options Optional parameters for the AI ask request. * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who * knows it can look up the job’s status. */ askWithAnnotations<T extends AiChatModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<AskResponse>; /** * Sends a prompt and not wait for the result - the result can be tracked using the job ID * (`squid.jobs().awaitJob(jobId)` or `squid.jobs().getJob(jobId)). * The result is of type AiAskResponse which contains the response string and optional annotations. * @param prompt The text prompt to send to the agent. * @param jobId A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who knows it can look up the job’s status. * @param options Optional parameters for the AI ask request. */ askAsync<T extends AiChatModelSelection | undefined = undefined>(prompt: string, jobId: JobId, options?: AiAskOptions<T>): Promise<void>; /** * Observes live status messages from the agent. * @param jobId The job ID to filter status updates for a specific job. If not provided, all status updates for the agent are observed. */ observeStatusUpdates(jobId?: JobId): Observable<AiStatusMessage>; /** * Returns a list of all chat history messages with the given 'memoryId'. * Includes both user and & AI messages. */ getChatHistory(memoryId: string): Promise<Array<AiChatMessage>>; /** * Transcribes audio and sends it to the agent for response. * @param fileToTranscribe The audio file to transcribe and send to the agent. * @param options Optional parameters for the AI ask request. * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who * knows it can look up the job’s status. */ transcribeAndAsk<T extends AiChatModelSelection | undefined>(fileToTranscribe: File, options?: AiAskOptions<T>, jobId?: JobId): Promise<AiTranscribeAndAskResponse>; /** * Transcribes audio and gets both text and voice response from the agent. * @param fileToTranscribe The audio file to transcribe and send to the agent. * @param options Optional parameters for the AI ask request. * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who * knows it can look up the job’s status. */ transcribeAndAskWithVoiceResponse<T extends AiChatModelSelection | undefined>(fileToTranscribe: File, options?: AiAskOptionsWithVoice<T>, jobId?: JobId): Promise<TranscribeAndAskWithVoiceResponse>; /** * Sends a prompt and gets both text and voice response from the agent. * @param prompt The text prompt to send to the agent. * @param options Optional parameters for the AI ask request. * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or * `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who * knows it can look up the job’s status. */ askWithVoiceResponse<T extends AiChatModelSelection | undefined>(prompt: string, options?: AiAskOptionsWithVoice<T>, jobId?: JobId): Promise<AskWithVoiceResponse>; /** * Sets a value at a specific path within the agent's options. */ setAgentOptionInPath(path: Paths<AllAiAgentChatOptions> | string, value: unknown): Promise<void>; /** * Atomically adds a connected integration to the agent. */ addConnectedIntegration(integration: AiConnectedIntegrationMetadata): Promise<void>; /** * Atomically adds a connected agent to the agent. */ addConnectedAgent(connectedAgent: AiConnectedAgentMetadata): Promise<void>; /** * Atomically adds a connected knowledge base to the agent. */ addConnectedKnowledgeBase(knowledgeBase: AiConnectedKnowledgeBaseMetadata): Promise<void>; /** * Atomically adds a function to the agent. */ addFunction(functionId: string): Promise<void>; /** * Atomically removes a connected agent from the agent. */ removeConnectedAgent(connectedAgentId: string): Promise<void>; /** * Atomically removes a connected integration from the agent. */ removeConnectedIntegration(integrationId: string): Promise<void>; /** * Atomically removes a connected knowledge base from the agent. */ removeConnectedKnowledgeBase(knowledgeBaseId: string): Promise<void>; /** * Atomically removes a function from the agent. */ removeFunction(functionId: string): Promise<void>; /** * Sets the agent's description. */ setAgentDescription(description: string): Promise<void>; /** * Submits a feedback string for the agent. Requires an API Key. * This feedback may update the agent's instructions, connected integrations, and may be forwarded to connected agents. * @param feedback The feedback to provide for the agent. */ provideFeedback(feedback: string): Promise<string>; /** * Uses an AI builder agent to modify this agent based on a natural language request. Requires an API Key. * The builder can update instructions, connect/disconnect integrations, add/remove functions, * connect other agents, manage knowledge bases, and configure guardrails. * * @param request A natural language description of what you want to build or change. * @param memoryId Optional memory ID for conversation history. If not provided, defaults to 'no-memory' (no persistence). * @param options Optional configuration for the build request. * @param options.canManageIntegrations Whether the caller has permission to create or update integrations. Defaults to false. * @returns A string describing what changes were made. */ build(request: string, memoryId?: string, options?: BuildAgentOptions): Promise<string>; /** * Helper to replace ${id:fileId} tags in the AI output with their corresponding Markdown. * @param aiResponse * @param annotations * @private */ private replaceFileTags; private askInternal; private chatInternal; /** * Merges the Squid-instance-level metric annotations under the per-call ones. * Returns the options unchanged when no annotations are set anywhere. */ private withMetricAnnotations; /** * Calls rpcManager post but with the agent api key if one was given during construction */ private post; }