SuperCharged-Claude-Code-Upgrade/dexto/packages/core/README.md

@dexto/core

The Dexto Agent SDK for building agentic applications programmatically. This package powers the Dexto CLI and lets you embed the same agent runtime in your own apps.

Installation

npm install @dexto/core

Optional Dependencies

Some features require additional packages. Install only what you need:

# Telemetry (OpenTelemetry distributed tracing)
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
  @opentelemetry/resources @opentelemetry/semantic-conventions \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http

# For gRPC telemetry export protocol
npm install @opentelemetry/exporter-trace-otlp-grpc

# Storage backends
npm install better-sqlite3  # SQLite database
npm install pg              # PostgreSQL database
npm install ioredis         # Redis cache

# TypeScript plugin support
npm install tsx

If you configure a feature without its dependencies, you'll get a helpful error message with the exact install command.

Note: The dexto CLI package includes all optional dependencies. These are only needed when using @dexto/core directly as a library.

Quick Start

import { DextoAgent } from '@dexto/core';

// Create and start agent
const agent = new DextoAgent({
  llm: {
    provider: 'openai',
    model: 'gpt-5-mini',
    apiKey: process.env.OPENAI_API_KEY
  }
});
await agent.start();

// Create a session for the conversation
const session = await agent.createSession();

// Use generate() for simple request/response
const response = await agent.generate('What is TypeScript?', session.id);
console.log(response.content);

// Conversations maintain context within a session
await agent.generate('Write a haiku about it', session.id);
await agent.generate('Make it funnier', session.id);

// Multimodal: send images or files
await agent.generate([
  { type: 'text', text: 'Describe this image' },
  { type: 'image', image: base64Data, mimeType: 'image/png' }
], session.id);

// Streaming for real-time UIs
for await (const event of await agent.stream('Write a story', session.id)) {
  if (event.name === 'llm:chunk') process.stdout.write(event.content);
}

await agent.stop();

See the Dexto Agent SDK docs for multimodal content, streaming, MCP tools, and advanced features.

---

Starting a Server

Start a Dexto server programmatically to expose REST and SSE streaming APIs to interact and manage your agent backend.

import { DextoAgent } from '@dexto/core';
import { startHonoApiServer } from 'dexto';

// Create and configure agent
const agent = new DextoAgent({
  llm: {
    provider: 'openai',
    model: 'gpt-5-mini',
    apiKey: process.env.OPENAI_API_KEY
  },
  mcpServers: {
    filesystem: {
      type: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
    }
  }
});

// Start server on port 3001
const { server } = await startHonoApiServer(agent, 3001);

console.log('Dexto server running at http://localhost:3001');
// Server provides REST API and SSE streaming endpoints
// POST /api/message - Send messages
// GET /api/sessions - List sessions
// See docs.dexto.ai/api/rest/ for all endpoints

This starts an HTTP server with full REST and SSE APIs, enabling integration with web frontends, webhooks, and other services. See the REST API Documentation for available endpoints.

Session Management

Create and manage multiple conversation sessions with persistent storage.

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

// Create and manage sessions
const session = await agent.createSession('user-123');
await agent.generate('Hello, how can you help me?', session.id);

// List and manage sessions
const sessions = await agent.listSessions();
const sessionHistory = await agent.getSessionHistory('user-123');
await agent.deleteSession('user-123');

// Search across conversations
const results = await agent.searchMessages('bug fix', { limit: 10 });

LLM Management

Switch between models and providers dynamically.

// Get current configuration
const currentLLM = agent.getCurrentLLMConfig();

// Switch models (provider inferred automatically)
await agent.switchLLM({ model: 'gpt-5-mini' });
await agent.switchLLM({ model: 'claude-sonnet-4-5-20250929' });

// Switch model for a specific session id 1234
await agent.switchLLM({ model: 'gpt-5-mini' }, '1234')

// Get supported providers and models
const providers = agent.getSupportedProviders();
const models = agent.getSupportedModels();
const openaiModels = agent.getSupportedModelsForProvider('openai');

MCP Manager

For advanced MCP server management, use the MCPManager directly.

import { MCPManager } from '@dexto/core';

const manager = new MCPManager();

// Connect to MCP servers
await manager.connectServer('filesystem', {
  type: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
});

// Access tools, prompts, and resources
const tools = await manager.getAllTools();
const prompts = await manager.getAllPrompts();
const resources = await manager.getAllResources();

// Execute tools
const result = await manager.executeTool('readFile', { path: './README.md' });

await manager.disconnectAll();

Agent-to-Agent Delegation

Delegate tasks to other A2A-compliant agents using the built-in delegate_to_url tool.

const agent = new DextoAgent({
  llm: { /* ... */ },
  internalTools: ['delegate_to_url'], // Enable delegation tool
  toolConfirmation: { mode: 'auto-approve' }
});
await agent.start();

const session = await agent.createSession();

// Delegate via natural language
await agent.generate(`
  Please delegate this task to the PDF analyzer agent at http://localhost:3001:
  "Extract all tables from the Q4 sales report"
`, session.id);

// Or call the tool directly
const tools = await agent.getAllTools();
const delegateTool = tools.find(t => t.name === 'internal--delegate_to_url');
// The tool is prefixed with 'internal--' by the ToolManager

Configuration (YAML):

internalTools:
  - delegate_to_url

What it provides:

• Point-to-point delegation when you know the agent URL
• A2A Protocol v0.3.0 compliant (JSON-RPC transport)
• Session management for stateful multi-turn conversations
• Automatic endpoint discovery (/v1/jsonrpc, /jsonrpc)
• Timeout handling and error recovery

Use cases:

• Multi-agent systems with known agent URLs
• Delegation to specialized agents
• Building agent workflows and pipelines
• Testing agent-to-agent communication

Telemetry

Built-in OpenTelemetry distributed tracing for observability.

const agent = new DextoAgent({
  llm: { /* ... */ },
  telemetry: {
    enabled: true,
    serviceName: 'my-agent',
    export: {
      type: 'otlp',
      endpoint: 'http://localhost:4318/v1/traces'
    }
  }
});

Automatically traces agent operations, LLM calls with token usage, and tool executions. See src/telemetry/README.md for details.

Logger

Multi-transport logging system (v2) with console, file, and remote transports. Configure in agent YAML:

logger:
  level: info  # error | warn | info | debug | silly
  transports:
    - type: console
      colorize: true
    - type: file
      path: ./logs/agent.log
      maxSize: 10485760
      maxFiles: 5

CLI automatically adds per-agent file transport at ~/.dexto/logs/<agent-id>.log. See architecture in src/logger/v2/.

See the DextoAgent API reference for all methods: https://docs.dexto.ai/api/dexto-agent/

---

Links

• Docs: https://docs.dexto.ai/
• Configuration Guide: https://docs.dexto.ai/docs/category/guides/
• API Reference: https://docs.dexto.ai/api/

License

Elastic License 2.0. See the repository LICENSE for details.