Skip to main content

DextoAgent API

Complete API reference for the main DextoAgent class. This is the core interface for the Dexto Agent SDK.

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​

The Dexto Agent SDK provides three methods for processing messages:

  • generate() - Recommended for most use cases. Returns a complete response.
  • stream() - For real-time streaming UIs. Yields events as they arrive.
  • run() - Lower-level method for direct control.

generate​

Recommended method for processing user input. Waits for complete response.

async generate(
  content: ContentInput,
  sessionId: string,
  options?: GenerateOptions
): Promise<GenerateResponse>
ParameterTypeDescription
contentstring | ContentPart[]User message (string) or multimodal content (array)
sessionIdstringRequired. Session ID for the conversation
options.signalAbortSignal(Optional) For cancellation

Content Types:

// Simple string content
type ContentInput = string | ContentPart[];

// For multimodal content, use ContentPart array:
type ContentPart = TextPart | ImagePart | FilePart;

interface TextPart { type: 'text'; text: string; }
interface ImagePart { type: 'image'; image: string; mimeType?: string; }
interface FilePart { type: 'file'; data: string; mimeType: string; filename?: string; }

Returns: Promise<GenerateResponse>

interface GenerateResponse {
  content: string;           // The AI's text response
  reasoning?: string;        // Extended thinking (o1/o3 models)
  usage: TokenUsage;         // Token usage statistics
  toolCalls: AgentToolCall[]; // Tools that were called
  sessionId: string;
  messageId: string;
}

Example:

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

const session = await agent.createSession();

// Simple text message
const response = await agent.generate('What is 2+2?', session.id);
console.log(response.content); // "4"
console.log(response.usage.totalTokens); // Token count

// With image URL (auto-detected)
const response = await agent.generate([
  { type: 'text', text: 'Describe this image' },
  { type: 'image', image: 'https://example.com/photo.jpg' }
], session.id);

// With image base64
const response = await agent.generate([
  { type: 'text', text: 'Describe this image' },
  { type: 'image', image: base64Image, mimeType: 'image/png' }
], session.id);

// With file URL
const response = await agent.generate([
  { type: 'text', text: 'Summarize this document' },
  { type: 'file', data: 'https://example.com/doc.pdf', mimeType: 'application/pdf' }
], session.id);

// With file base64
const response = await agent.generate([
  { type: 'text', text: 'Summarize this document' },
  { type: 'file', data: base64Pdf, mimeType: 'application/pdf', filename: 'doc.pdf' }
], session.id);

// With cancellation support
const controller = new AbortController();
const response = await agent.generate('Long task...', session.id, { signal: controller.signal });

await agent.stop();

stream​

For real-time streaming UIs. Yields events as they arrive.

async stream(
  content: ContentInput,
  sessionId: string,
  options?: StreamOptions
): Promise<AsyncIterableIterator<StreamingEvent>>
ParameterTypeDescription
contentstring | ContentPart[]User message (string) or multimodal content (array)
sessionIdstringRequired. Session ID
options.signalAbortSignal(Optional) For cancellation

Returns: Promise<AsyncIterableIterator<StreamingEvent>>

Example:

const session = await agent.createSession();

// Simple text streaming
for await (const event of await agent.stream('Write a poem', session.id)) {
  if (event.name === 'llm:chunk') {
    process.stdout.write(event.content);
  }
  if (event.name === 'llm:tool-call') {
    console.log(`\n[Using ${event.toolName}]\n`);
  }
}

// Streaming with image
for await (const event of await agent.stream([
  { type: 'text', text: 'Describe this image' },
  { type: 'image', image: base64Image, mimeType: 'image/png' }
], session.id)) {
  if (event.name === 'llm:chunk') {
    process.stdout.write(event.content);
  }
}

run​

Lower-level method for direct control. Prefer generate() for most use cases.

async run(
  textInput: string,
  imageDataInput: { image: string; mimeType: string } | undefined,
  fileDataInput: { data: string; mimeType: string; filename?: string } | undefined,
  sessionId: string,
  stream?: boolean
): Promise<string>
ParameterTypeDescription
textInputstringUser message or query
imageDataInput{ image: string; mimeType: string } | undefinedImage data or undefined
fileDataInput{ data: string; mimeType: string; filename?: string } | undefinedFile data or undefined
sessionIdstringRequired. Session ID
streamboolean(Optional) Enable streaming (default: false)

Returns: Promise<string> - AI response text

Example:

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

const session = await agent.createSession();

// Recommended: Use generate() for most use cases
const response = await agent.generate(
  "Explain quantum computing",
  session.id
);
console.log(response.content);

// Lower-level run() method (returns just the text)
const responseText = await agent.run(
  "Explain quantum computing",
  undefined,  // no image
  undefined,  // no file
  session.id
);

await agent.stop();

cancel​

Cancels the currently running turn for a session.

async cancel(sessionId: string): Promise<boolean>
ParameterTypeDescription
sessionIdstringRequired. Session ID to cancel

Returns: Promise<boolean> - true if a run was in progress and cancelled

Session Management​

Architectural Pattern

DextoAgent's core is stateless and does not track a "current" or "default" session. All session-specific operations require an explicit sessionId parameter. Application layers (CLI, WebUI, API servers) are responsible for managing which session is active in their own context.

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>

Example:

// Create a new session (auto-generated ID)
const session = await agent.createSession();
console.log(`Created session: ${session.id}`);

// Create a session with custom ID
const userSession = await agent.createSession('user-123');

// Use the session for conversations
await agent.generate("Hello!", session.id);

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.

resetConversation​

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

async resetConversation(sessionId: string): Promise<void>
ParameterTypeDescription
sessionIdstringSession ID 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>

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, 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-sonnet-4-5-20250929' 
});
console.log(config.model);

getCurrentLLMConfig​

Returns the base LLM configuration from the agent's initialization config.

getCurrentLLMConfig(): LLMConfig

Returns: LLMConfig - The base LLM configuration (does not include session-specific overrides)

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​

addMcpServer​

Adds and connects to a new MCP server, making its tools available to the agent.

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

removeMcpServer​

Disconnects from an MCP server and removes it completely from the agent.

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

enableMcpServer​

Enables a disabled MCP server and connects it.

async enableMcpServer(name: string): Promise<void>
ParameterTypeDescription
namestringServer name to enable

disableMcpServer​

Disables an MCP server and disconnects it. The server remains registered but inactive.

async disableMcpServer(name: string): Promise<void>
ParameterTypeDescription
namestringServer name to disable

restartMcpServer​

Restarts an MCP server by disconnecting and reconnecting with its original configuration.

async restartMcpServer(name: string): Promise<void>
ParameterTypeDescription
namestringServer name to restart

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>