tdx

Appearance

SDK API Reference / LLMSDK

Class: LLMSDK ​

LLM operations API

Methods ​

agent() ​

agent(agentId): Promise<Agent>

Get a specific agent by ID

Parameters ​

agentId ​

string

Agent ID

Returns ​

Promise<Agent>

Agent details

Throws ​

When the get operation fails

Example ​

typescript
const agent = await tdx.llm.agent('agent123');

agents() ​

agents(projectId?): Promise<Agent[]>

List agents (optionally filtered by project)

Uses current project context if no projectId provided.

Parameters ​

projectId? ​

string

Optional project ID to filter agents (defaults to current project)

Returns ​

Promise<Agent[]>

List of agents (full JSON:API format)

Throws ​

When the list operation fails

Example ​

typescript
// List agents in current project
const agents = await tdx.llm.agents();

// List agents for specific project
const agents = await tdx.llm.agents('project123');

backupProject() ​

backupProject(projectNameOrId, outputDir?, options?): Promise<BackupSummary>

Backup an LLM project to a folder

Creates a folder structure containing all project entities:

  • project.json: Project metadata and backup info
  • agents.json: All agents with full configuration
  • prompts.json: All prompts
  • knowledgebases.json: All knowledge bases
  • integrations.json: All integrations

Parameters ​

projectNameOrId ​

string

Project name or ID to backup

outputDir? ​

string

Output folder path (default: {project_name}.llm)

options? ​

Backup options

dryRun? ​

boolean

If true, only analyze what would be backed up without creating files

Returns ​

Promise<BackupSummary>

Backup summary with counts and output location

Throws ​

When project not found or backup fails

Example ​

typescript
const summary = await tdx.llm.backupProject('My Project');
// Creates My Project.llm/ folder with all entities

const summary = await tdx.llm.backupProject('My Project', './backups/myproject');
// Creates ./backups/myproject/ folder

const summary = await tdx.llm.backupProject('My Project', undefined, { dryRun: true });
// Only analyzes what would be backed up without creating files

chat() ​

chat(message, options?): AsyncGenerator<ChatStreamEvent, void, unknown>

Start or continue a chat session with streaming responses

This method returns an async generator that yields SSE events as they arrive from the LLM. Events can be:

  • Content events: Text chunks from the LLM
  • Tool call events: LLM requesting tool execution
  • Tool result events: Tool execution results
  • Output events: Structured outputs (e.g., Plotly charts)
  • Error events: Error messages

Parameters ​

message ​

string

User message to send

options? ​

ChatOptions

Chat options (signal, chatId, agentId, projectId)

Returns ​

AsyncGenerator<ChatStreamEvent, void, unknown>

Async generator yielding SSE events

Throws ​

When the chat operation fails

Example ​

typescript
// Start new chat with agent
for await (const event of tdx.llm.chat('Hello', { agentId: 'agent123' })) {
  if ('content' in event) {
    process.stdout.write(event.content);
  } else if ('error' in event) {
    console.error('Error:', event.error);
  }
}

// Continue existing chat
for await (const event of tdx.llm.chat('Follow up question', {
  chatId: 'chat456'
})) {
  // Process events...
}

// With cancellation support
const controller = new AbortController();
setTimeout(() => controller.abort(), 30000); // Cancel after 30s

try {
  for await (const event of tdx.llm.chat('Long query', {
    agentId: 'agent123',
    signal: controller.signal
  })) {
    // Process events...
  }
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Chat cancelled');
  }
}

chatInfo() ​

chatInfo(chatId): Promise<Chat>

Get chat info

Parameters ​

chatId ​

string

Chat session ID

Returns ​

Promise<Chat>

Chat session info

Throws ​

When the get operation fails

Example ​

typescript
const chat = await tdx.llm.chatInfo('chat123');
console.log('Agent:', chat.attributes.agentId);
console.log('Created:', chat.attributes.createdAt);

chats() ​

chats(limit): Promise<Chat[]>

List chat sessions

Parameters ​

limit ​

number = 50

Maximum number of chats to return (default: 50)

Returns ​

Promise<Chat[]>

List of chat sessions sorted by last conversation time

Throws ​

When the list operation fails

Example ​

typescript
const chats = await tdx.llm.chats();

createAgent() ​

createAgent(params): Promise<Agent>

Create a new agent

Parameters ​

params ​

CreateAgentParams

Agent creation parameters

Returns ​

Promise<Agent>

Created agent

Throws ​

When the create operation fails

Example ​

typescript
const agent = await tdx.llm.createAgent({
  name: 'My Agent',
  description: 'A helpful assistant',
  prompt: 'You are a helpful data analyst...',
  projectId: 'project123',
  starterMessage: 'Hello! How can I help you?'
});

createProject() ​

createProject(params): Promise<LLMProject>

Create a new LLM project

Parameters ​

params ​

CreateProjectParams

Project creation parameters

Returns ​

Promise<LLMProject>

Created project

Throws ​

When the create operation fails

Example ​

typescript
const project = await tdx.llm.createProject({
  name: 'My Project',
  description: 'Project description'
});

deleteAgent() ​

deleteAgent(agentId): Promise<void>

Delete an agent

Parameters ​

agentId ​

string

Agent ID

Returns ​

Promise<void>

Throws ​

When the delete operation fails

Example ​

typescript
await tdx.llm.deleteAgent('agent123');

deleteProject() ​

deleteProject(nameOrId): Promise<void>

Delete an LLM project

Resolves project name to ID if needed, validates existence, then deletes.

Parameters ​

nameOrId ​

string

Project name or ID

Returns ​

Promise<void>

Throws ​

When the delete operation fails

Example ​

typescript
await tdx.llm.deleteProject('My Project');
// or with ID
await tdx.llm.deleteProject('project123');

getBackupMetadata() ​

getBackupMetadata(inputDir): ProjectBackupMetadata

Get backup metadata from a backup folder

Reads and validates the project.json file from a backup folder. Useful for previewing backup contents before restore.

Parameters ​

inputDir ​

string

Path to backup folder

Returns ​

ProjectBackupMetadata

Backup metadata including project name, export info, and version

Throws ​

When backup folder or project.json not found, or version unsupported

Example ​

typescript
const metadata = await tdx.llm.getBackupMetadata('./My Project.llm');
console.log(`Project: ${metadata.exportedFrom.projectName}`);
console.log(`Exported at: ${metadata.exportedAt}`);

getCurrentProject() ​

getCurrentProject(): string | undefined

Get current project context

Returns the project ID set via setCurrentProject(), or undefined if not set.

Returns ​

string | undefined

Current project ID or undefined

Example ​

typescript
const projectId = tdx.llm.getCurrentProject();
if (projectId) {
  console.log('Using project:', projectId);
}

getOrCreateDefaultAgent() ​

getOrCreateDefaultAgent(model, reasoningEffort, temperature?): Promise<Agent>

Get or create agent for a specific model in user's default project

Agent names are based on model to allow reuse:

  • claude-4.5-sonnet → tdx_claude-4.5-sonnet
  • gpt-5 → tdx_gpt-5
  • nova-pro-v1 → tdx_nova-pro-v1

Parameters ​

model ​

string = 'claude-4.5-sonnet'

Model name (default: claude-4.5-sonnet)

reasoningEffort ​

number = 0

Reasoning effort level: 0=NONE, 1=MINIMAL, 2=LOW, 3=MEDIUM, 4=HIGH (default: 0)

temperature? ​

number

Temperature setting (default: 0.7)

Returns ​

Promise<Agent>

Agent for the specified model and reasoning level

Throws ​

When operation fails

Example ​

typescript
const agent = await tdx.llm.getOrCreateDefaultAgent();
const agent = await tdx.llm.getOrCreateDefaultAgent('claude-4.5-sonnet', 4); // HIGH
const agent = await tdx.llm.getOrCreateDefaultAgent('claude-4.5-sonnet', 3, 0.5); // MEDIUM

getOrCreateDefaultProject() ​

getOrCreateDefaultProject(projectName?): Promise<LLMProject>

Get or create default project by name Simple lookup/creation - no retry logic (handled by caller)

Uses cached project ID for fast lookup when available, avoiding the need to scan all projects on every startup.

Parameters ​

projectName? ​

string

Optional project name (defaults to user-specific name)

Returns ​

Promise<LLMProject>

Default project

Throws ​

When operation fails

history() ​

history(chatId): Promise<ChatHistoryResponse>

Get chat history

Parameters ​

chatId ​

string

Chat session ID

Returns ​

Promise<ChatHistoryResponse>

Chat history with messages

Throws ​

When the history operation fails

Example ​

typescript
const history = await tdx.llm.history('chat123');
for (const msg of history.messages) {
  console.log(`${msg.role}: ${msg.content}`);
}

models() ​

models(): Promise<ModelInfo[]>

Get available LLM models

Returns list of available models with their display names

Returns ​

Promise<ModelInfo[]>

List of available models

Throws ​

When the operation fails

Example ​

typescript
const models = await tdx.llm.models();
// [
//   { name: 'claude-4.5-sonnet', displayName: 'Claude 4.5 Sonnet' },
//   { name: 'gpt-5', displayName: 'GPT-5' },
//   ...
// ]

projects() ​

projects(limit): Promise<LLMProject[]>

List all LLM projects

Parameters ​

limit ​

number = 50

Maximum number of projects per page (default: 50)

Returns ​

Promise<LLMProject[]>

List of LLM projects (full JSON:API format)

Throws ​

When the list operation fails

Example ​

typescript
// List all projects
const projects = await tdx.llm.projects();

// List with custom limit per page
const projects = await tdx.llm.projects(100);

resolveAgentId() ​

resolveAgentId(agentName, projectId?): Promise<string>

Resolve agent name to ID (optionally within a project)

Uses current project context if no projectId provided.

Parameters ​

agentName ​

string

Agent name

projectId? ​

string

Optional project ID to narrow search (defaults to current project)

Returns ​

Promise<string>

Agent ID

Throws ​

When agent is not found or name is ambiguous

Example ​

typescript
const agentId = await tdx.llm.resolveAgentId('My Agent');
const agentId = await tdx.llm.resolveAgentId('My Agent', 'project123');

resolveProjectId() ​

resolveProjectId(projectName): Promise<string>

Resolve project name to ID

Parameters ​

projectName ​

string

Project name

Returns ​

Promise<string>

Project ID

Throws ​

When project is not found or name is ambiguous

Example ​

typescript
const projectId = await tdx.llm.resolveProjectId('My Project');

restoreProject() ​

restoreProject(inputDir, options?): Promise<RestoreSummary>

Restore an LLM project from a backup folder

Creates a new project and restores all entities with proper ID remapping. Entity dependencies are handled in the correct order:

  1. Project (created first)
  2. Knowledge bases (agents may reference them)
  3. Agents (with dependency ordering for agent-to-agent references)
  4. Prompts (reference agents)
  5. Integrations (reference prompts)

Parameters ​

inputDir ​

string

Path to backup folder

options? ​

Restore options

dryRun? ​

boolean

If true, validate backup and report what would be restored without making changes

name? ​

string

New project name (defaults to original name from backup)

Returns ​

Promise<RestoreSummary>

Restore summary with created entity counts

Throws ​

When backup invalid or restore fails

Example ​

typescript
const summary = await tdx.llm.restoreProject('./My Project.llm');
// Creates project with original name

const summary = await tdx.llm.restoreProject('./backup', { name: 'New Project' });
// Creates project with new name

const summary = await tdx.llm.restoreProject('./backup', { dryRun: true });
// Validates backup and reports what would be restored

setCurrentProject() ​

setCurrentProject(nameOrId): Promise<void>

Set current project context for agent operations

Resolves project name to ID and stores it in session memory. This context is used as the default for agent operations.

Parameters ​

nameOrId ​

string

Project name or ID

Returns ​

Promise<void>

Throws ​

When project is not found

Example ​

typescript
await tdx.llm.setCurrentProject('My Project');
// Now agent operations will default to this project

startChat() ​

startChat(agentId): Promise<Chat>

Create a new chat session

Parameters ​

agentId ​

string

Agent ID to use for the chat

Returns ​

Promise<Chat>

Chat object with id and metadata

Throws ​

When chat creation fails

Example ​

typescript
const chat = await tdx.llm.startChat('agent123');
console.log('Created chat:', chat.id);

updateAgent() ​

updateAgent(agentId, params): Promise<Agent>

Update an existing agent

Parameters ​

agentId ​

string

Agent ID

params ​

UpdateAgentParams

Agent update parameters

Returns ​

Promise<Agent>

Updated agent

Throws ​

When the update operation fails

Example ​

typescript
const agent = await tdx.llm.updateAgent('agent123', {
  name: 'Updated Name',
  starterMessage: 'Hi there!'
});

Copyright 2024-present Treasure Data