Skip to main content

DextoAgent API

Complete API reference for the main DextoAgent class.

Constructor and Lifecycle​

constructor​

Creates a new Dexto agent instance with the provided configuration.

constructor(config: AgentConfig)
ParameterTypeDescription
configAgentConfigAgent configuration object

start​

Initializes and starts the agent with all required services.

async start(): Promise<void>

Parameters: None

Example:

const agent = new DextoAgent(config);
await agent.start();

stop​

Stops the agent and cleans up all resources.

async stop(): Promise<void>

Example:

await agent.stop();

Core Methods​

run​

Processes user input through the agent's LLM and returns the response.

async run(
  textInput: string,
  imageDataInput?: { base64: string; mimeType: string },
  fileDataInput?: { base64: string; mimeType: string; filename?: string },
  sessionId?: string,
  stream?: boolean
): Promise<string | null>
ParameterTypeDescription
textInputstringUser message or query
imageDataInput{ base64: string; mimeType: string }(Optional) Base64-encoded image
fileDataInput{ base64: string; mimeType: string; filename?: string }(Optional) Base64-encoded file
sessionIdstring(Optional) Session ID
streamboolean(Optional) Enable streaming (default: false)

Returns: Promise<string | null> - AI response or null

Example:

const agent = new DextoAgent(config);
await agent.start();
const response = await agent.run("Explain quantum computing");
// ... use agent ...
await agent.stop();

Session Management​

createSession​

Creates a new conversation session with optional custom ID.

async createSession(sessionId?: string): Promise<ChatSession>
ParameterTypeDescription
sessionIdstring(Optional) Custom session ID

Returns: Promise<ChatSession>

getSession​

Retrieves an existing session by its ID.

async getSession(sessionId: string): Promise<ChatSession | undefined>
ParameterTypeDescription
sessionIdstringSession ID to retrieve

Returns: Promise<ChatSession | undefined>

listSessions​

Returns an array of all active session IDs.

async listSessions(): Promise<string[]>

Returns: Promise<string[]> - Array of session IDs

deleteSession​

Permanently deletes a session and all its conversation history. This action cannot be undone.

async deleteSession(sessionId: string): Promise<void>
ParameterTypeDescription
sessionIdstringSession ID to delete

Note: This completely removes the session and all associated conversation data from storage.

loadSession​

Sets a session as the default for subsequent operations that don't specify a session ID.

async loadSession(sessionId: string | null): Promise<void>
ParameterTypeDescription
sessionIdstring | nullSession ID to load as default, or null to reset

resetConversation​

Clears the conversation history of a session while keeping the session active.

async resetConversation(sessionId?: string): Promise<void>
ParameterTypeDescription
sessionIdstring(Optional) Session to reset

getSessionMetadata​

Retrieves metadata for a session including creation time and message count.

async getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>
ParameterTypeDescription
sessionIdstringSession ID

Returns: Promise<SessionMetadata | undefined>

getSessionHistory​

Gets the complete conversation history for a session.

async getSessionHistory(sessionId: string): Promise<ConversationHistory>
ParameterTypeDescription
sessionIdstringSession ID

Returns: Promise<ConversationHistory>

getCurrentSessionId​

Returns the ID of the currently loaded default session.

getCurrentSessionId(): string

Returns: string - Current default session ID

getDefaultSession​

Returns the currently loaded default session instance.

async getDefaultSession(): Promise<ChatSession>

Returns: Promise<ChatSession>

Configuration​

switchLLM​

Dynamically changes the LLM configuration for the agent or a specific session.

async switchLLM(
  llmUpdates: LLMUpdates,
  sessionId?: string
): Promise<ValidatedLLMConfig>
ParameterTypeDescription
llmUpdatesLLMUpdatesLLM configuration updates (model, provider, router, apiKey, etc.)
sessionIdstring(Optional) Target session ID

Returns: Promise<ValidatedLLMConfig> – the fully validated, effective LLM configuration.

const config = await agent.switchLLM({ 
  provider: 'anthropic', 
  model: 'claude-4-sonnet-20250514' 
});
console.log(config.model);

getCurrentLLMConfig​

Returns the current LLM configuration for the default session.

getCurrentLLMConfig(): LLMConfig

Returns: LLMConfig

getEffectiveConfig​

Gets the complete effective configuration for a session or the default configuration.

getEffectiveConfig(sessionId?: string): Readonly<AgentConfig>
ParameterTypeDescription
sessionIdstring(Optional) Session ID

Returns: Readonly<AgentConfig>

MCP Server Management​

connectMcpServer​

Connects to a new MCP server and adds it to the agent's available tools.

async connectMcpServer(name: string, config: McpServerConfig): Promise<void>
ParameterTypeDescription
namestringServer name
configMcpServerConfigServer configuration

removeMcpServer​

Disconnects from an MCP server and removes its tools from the agent.

async removeMcpServer(name: string): Promise<void>
ParameterTypeDescription
namestringServer name to remove

executeTool​

Executes a tool from any source (MCP servers, custom tools, or internal tools). This is the unified interface for tool execution.

async executeTool(toolName: string, args: any): Promise<any>
ParameterTypeDescription
toolNamestringTool name
argsanyTool arguments

Returns: Promise<any> - Tool execution result

getAllMcpTools​

Returns a map of all available tools from all connected MCP servers.

async getAllMcpTools(): Promise<Record<string, ToolDefinition>>

Returns: Promise<Record<string, ToolDefinition>>

getAllTools​

Returns a map of all available tools from all sources (MCP servers, custom tools, and internal tools). This is the unified interface for tool discovery.

async getAllTools(): Promise<Record<string, ToolDefinition>>

Returns: Promise<Record<string, ToolDefinition>>

getMcpClients​

Returns a map of all connected MCP client instances.

getMcpClients(): Map<string, IMCPClient>

Returns: Map<string, IMCPClient>

getMcpFailedConnections​

Returns a record of failed MCP server connections and their error messages.

getMcpFailedConnections(): Record<string, string>

Returns: Record<string, string> - Failed connection names to error messages

Model & Provider Introspection​

getSupportedProviders​

Returns the list of supported LLM providers.

getSupportedProviders(): LLMProvider[]

getSupportedModels​

Returns supported models grouped by provider, including a flag for the default model per provider.

getSupportedModels(): Record<LLMProvider, Array<ModelInfo & { isDefault: boolean }>>

getSupportedModelsForProvider​

Returns supported models for a specific provider.

getSupportedModelsForProvider(provider: LLMProvider): Array<ModelInfo & { isDefault: boolean }>

inferProviderFromModel​

Infers the provider from a model name or returns null if unknown.

inferProviderFromModel(modelName: string): LLMProvider | null

searchMessages​

Search for messages across all sessions or within a specific session.

async searchMessages(query: string, options?: SearchOptions): Promise<SearchResponse>

searchSessions​

Search for sessions that contain the specified query.

async searchSessions(query: string): Promise<SessionSearchResponse>