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

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

// 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

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

// 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

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

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

---

clearDefaultAgent()

clearDefaultAgent(): void

Clear default agent preference

Removes the cached default agent setting.

Returns

void

Example

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

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

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

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

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

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

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

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

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

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

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

// 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

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

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

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

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

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

// 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

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

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