tdx

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');

agentsFull() ​

agentsFull(projectId): Promise<AgentResponse[]>

List agents with full details (including tools, outputs, variables)

Parameters ​

projectId ​

string

Optional project ID (uses current project if not specified)

Returns ​

Promise<AgentResponse[]>

Array of agents with full attributes

Throws ​

When the list operation fails

backupProject() ​

backupProject(projectName, 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 ​

projectName ​

string

Project name 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();

clearDefaultAgent() ​

clearDefaultAgent(): void

Clear default agent preference

Removes the cached default agent setting.

Returns ​

void

Example ​

typescript
tdx.llm.clearDefaultAgent();

cloneProject() ​

cloneProject(source, newProjectName, options?): Promise<AgentCloneSummary>

Clone an LLM project to a new project

Creates a copy of an existing project (from remote or local files) with a new name.

Parameters ​

source ​

string

Source project name/ID or local path with tdx.json

newProjectName ​

string

Name for the new project

options? ​

AgentCloneOptions

Clone options

Returns ​

Promise<AgentCloneSummary>

Clone summary with counts and results

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(name): Promise<void>

Delete an LLM project

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

Parameters ​

name ​

string

Project name

Returns ​

Promise<void>

Throws ​

When the delete operation fails

Example ​

typescript
await tdx.llm.deleteProject('My Project');

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}`);

getChatLog() ​

getChatLog(chatId): Promise<ChatLogResponse>

Get chat log (experimental)

Parameters ​

chatId ​

string

Chat session ID

Returns ​

Promise<ChatLogResponse>

Chat log

Throws ​

When the get operation fails

Example ​

typescript
const log = await tdx.llm.getChatLog('chat123');
console.log('Log data:', log.data);

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);
}

getDefaultAgent() ​

getDefaultAgent(): { id: string; name: string; projectId: string; } | undefined

Get default agent for chat operations

Returns cached agent info if available, or undefined if no default is set.

Returns ​

{ id: string; name: string; projectId: string; } | undefined

Cached agent info or undefined

Example ​

typescript
const agent = tdx.llm.getDefaultAgent();
if (agent) {
  console.log('Default agent:', agent.name);
}

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);

pullAgent() ​

pullAgent(projectName, agentName, outputDir?, options?): Promise<AgentPullResult>

Pull a single agent from a project

Parameters ​

projectName ​

string

Project name

agentName ​

string

Agent name to pull

outputDir? ​

string

Output directory

options? ​

AgentPullOptions

Pull options

Returns ​

Promise<AgentPullResult>

Pull result for the agent

pullProject() ​

pullProject(projectName, outputDir?, options?): Promise<AgentPullSummary>

Pull all resources from an LLM project to local files

Creates folder structure:

  • agents/{project-name}/tdx.json
  • agents/{project-name}/{agent-name}/prompt.md
  • agents/{project-name}/{agent-name}/agent.yml
  • agents/{project-name}/knowledge_bases/{kb-name}.yml
  • agents/{project-name}/prompts/{prompt-name}.yml
  • agents/{project-name}/integrations/{integration-name}.yml

Parameters ​

projectName ​

string

Project name

outputDir? ​

string

Output directory (defaults to agents/{normalized-project-name}/)

options? ​

AgentPullOptions

Pull options

Returns ​

Promise<AgentPullSummary>

Pull summary with counts and file paths

pushAgent() ​

pushAgent(agentPath, options?): Promise<AgentPushResult>

Push a single agent from local files

Parameters ​

agentPath ​

string

Path to agent directory or agent.yml file

options? ​

AgentPushOptions

Push options

Returns ​

Promise<AgentPushResult>

Push result for the agent

pushProject() ​

pushProject(inputDir, options?): Promise<AgentPushSummary>

Push local agent files to an LLM project

Reads folder structure and syncs to API:

  • Creates/updates knowledge bases first (no dependencies)
  • Creates/updates agents (may depend on KBs and other agents)
  • Creates/updates prompts (depend on agents)
  • Creates/updates integrations (safe types only: CHAT_GENERIC, CHAT_AGENT_CONSOLE, CHAT_PARENT_SEGMENT)

Note: WEBHOOK and SLACK integrations contain secrets and will be rejected with a warning.

Parameters ​

inputDir ​

string

Input directory containing tdx.json and resource folders

options? ​

AgentPushOptions

Push options

Returns ​

Promise<AgentPushSummary>

Push summary with counts and results

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');

resolveProjectName() ​

resolveProjectName(name): Promise<{ project: LLMProject; projectId: string; }>

Resolve project name to project ID and instance

Parameters ​

name ​

string

Project name

Returns ​

Promise<{ project: LLMProject; projectId: string; }>

Object containing project ID and full project instance

Throws ​

When project is not found

Example ​

typescript
const { projectId, project } = await tdx.llm.resolveProjectName('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(name): 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 ​

name ​

string

Project name

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

setDefaultAgent() ​

setDefaultAgent(agentRef): Promise<void>

Set default agent for chat operations

Stores agent preference in cache for future chat commands. The agent reference can be either a full path "project/agent" or just "agent" name. When only agent name is provided, uses current project context or default project.

Parameters ​

agentRef ​

string

Agent reference (format: "agent-name" or "project/agent")

Returns ​

Promise<void>

Throws ​

When agent or project is not found

Example ​

typescript
// Set agent in current project
await tdx.llm.setDefaultAgent('MyAgent');

// Set agent with explicit project
await tdx.llm.setDefaultAgent('MyProject/MyAgent');

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 AI