Skip to content
Imbrace SDK

AI Agent

This page covers two related AI namespaces:

  • chatAi / chat_ai — create and manage AI agents, document/file processing, and document AI.
  • aiAgent / ai_agent — streaming chat (SSE), embedding management, Parquet data, distributed tracing, and the Chat Client sub-API.

The AI Agent resource connects to a dedicated service that runs on a separate base URL from the main API gateway.

For an end-to-end example that ties these together, see Full Flow Guide §1.

import { ImbraceClient } from "@imbrace/sdk"


const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env: "stable",
})
 
import { ImbraceClient } from "@imbrace/sdk"


const client = new ImbraceClient({
  apiKey: process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  env: "stable",
})

Both sync (ImbraceClient) and async (AsyncImbraceClient) clients expose the same surface — async methods are awaited and the client uses AsyncAiAgentResource under the hood.

AI Agents — chatAi / chat_ai

Manages AI agents (CRUD), runs OpenAI-compatible completions, and handles document/file processing. The same namespace also covers Knowledge Hub folders and knowledge bases.

AI Agent CRUD

// List all AI agents in your account
const agents = await client.chatAi.listAiAgents();
// Each AI agent has an `id` (UUID).
// Use the `id` field for all subsequent calls.


// List sub-agents (agents that can be delegated to by an orchestrator)
const subAgents = await client.chatAi.listAiAgentSubAgents();


// Get a single AI agent
const agent = await client.chatAi.getAiAgent("9f77692f-33d0-436a-8138-2efb268838e6");


// Create. The SDK auto-fills { provider_id: "system", model_id: "Default" }
// when omitted; "Default" routes to the org's configured default model and
// is org-portable. A literal name like "gpt-4o" only works if the org's
// system provider actually exposes it — `client.ai.listModels()` shows what's
// available. Pass `streaming: true` so /v2/chat emits text-delta SSE events
// that `streamChatText` (below) can parse; without it the server returns the
// full reply as one text/plain response and SSE parsers yield nothing.
const created = await client.chatAi.createAiAgent({
  name: "Support Bot",
  workflow_name: "support_bot_v1",
  provider_id: "system",
  model_id: "Default",
  streaming: true,
  description: "Handles tier-1 support queries",
});


// Update — all fields are optional (Partial)
const updated = await client.chatAi.updateAiAgent(created.id, {
  name: "Support Bot v2",
  workflow_name: "support_bot_v1",
});


// Update only the system instructions
await client.chatAi.updateAiAgentInstructions(
  created.id,
  "You are a helpful support agent.",
);


await client.chatAi.deleteAiAgent(created.id);

Completions (via client.ai)

OpenAI-compatible chat completions are available on the client.ai namespace for both TypeScript and Python. See the OpenAI-compatible AI service section below for details.

const response = await client.ai.complete({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful CRM assistant." },
    { role: "user", content: "Summarize this customer note: ..." },
  ],
});
console.log(response.choices[0].message.content);

Document AI models

const models = await client.chatAi.listDocumentModels();

Document AI

Extract structured data from PDFs and images using a vision model. See the Document AI reference for the full parameter reference, PDF form filling, and async usage.

File extraction (agent file upload)

Upload a file and extract its raw content.

// Upload an agent-specific file
const formData = new FormData();
formData.append("file", fileBuffer, "report.pdf");
const uploaded = await client.chatAi.uploadAgentFile(formData);


// Extract content from an uploaded file
const extracted = await client.chatAi.extractFile(formData);

Chat v1 sessions

Legacy REST chat endpoints for persisting conversation history. Available on client.ai_agent for both TypeScript and Python. See Legacy v1 chat below.

Knowledge Hub — folders & knowledge bases

Folders and knowledge bases are managed via client.boards (TypeScript) / client.folders and client.boards (Python). Folders organize knowledge bases — a knowledge base is a set of files an AI agent can retrieve from. Pass folder IDs as folder_ids when creating an AI agent — see Full Flow Guide §3.

import { type CreateFolderInput } from "@imbrace/sdk";


// Folders
const folders = await client.boards.searchFolders({ organizationId: "org_xxx" });
const folder  = await client.boards.createFolder({ name: "Q1 Reports" });
await client.boards.updateFolder(folder._id, { name: "Q1 2025 Reports" });
await client.boards.deleteFolders({ ids: [folder._id] });


// Files (knowledge base entries)
const uploaded = await client.boards.uploadFile(formData);
const files    = await client.boards.searchFiles({ folderId: folder._id });
const file     = await client.boards.getFile("file_id");
await client.boards.createFile({ name: "doc.txt", folder_id: folder._id });
await client.boards.deleteFiles({ ids: ["file_id"] });

OpenAI-compatible AI service — client.ai

OpenAI-style completions, streaming, and embeddings. Also exposes management APIs for LLM models, providers, guardrails, RAG files, and AI agents. Available for both TypeScript and Python.

// Single completion
const response = await client.ai.complete({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful CRM assistant." },
    { role: "user",   content: "Summarize this customer note: ..." },
  ],
  temperature: 0.7,
});
console.log(response.choices[0].message.content);


// Streaming
const stream = client.ai.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Draft a follow-up email for this lead." }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content ?? "");
}


// Embeddings
const result = await client.ai.embed({
  model: "text-embedding-ada-002",
  input: ["customer complained about billing", "billing issue escalated"],
});

LLM Models

List models available for AI agents and workflow agents.

const result = await client.ai.getLlmModels();
// result.data → [{name, is_toolCall_available, is_vision_available, is_support_thinking}]
for (const model of result.data) {
  console.log(model.name, model.is_toolCall_available);
}

Providers

Manage custom LLM providers. listProviders includes a synthetic "system" entry (provider_id: "system") representing the built-in models from getLlmModels.

// List all providers (includes system default as first entry)
const providers = await client.ai.listProviders();
// Custom providers only
const custom = await client.ai.listProviders({ includeSystem: false });


// Add a custom provider
const provider = await client.ai.createProvider({
  name: "My Azure OpenAI",
  type: "azure",
  api_key: "sk-...",
  base_url: "https://my-instance.openai.azure.com/",
});


// Update, refresh models, delete
await client.ai.updateProvider(provider._id, { name: "Azure OpenAI (prod)" });
await client.ai.refreshProviderModels(provider._id);
await client.ai.deleteProvider(provider._id);

Guardrails

Filter AI agent output for safety, policy compliance, or brand guidelines.

// List and get
const guardrails = await client.ai.listGuardrails();
const guardrail  = await client.ai.getGuardrail("guardrail_id");


// Create
const created = await client.ai.createGuardrail({
  name: "Brand Safety",
  model: "gpt-4o",
  instructions: "Block responses that mention competitor names.",
  unsafe_categories: ["violence", "hate_speech"],
  competitor_keywords: ["CompetitorA", "CompetitorB"],
});


// Update and delete
await client.ai.updateGuardrail(created._id, {
  name: "Brand Safety v2",
  model: "gpt-4o",
  instructions: "Updated instructions.",
});
await client.ai.deleteGuardrail(created._id);

Guardrail Providers

Manage LLM providers that power guardrail evaluation.

// List and get
const providers = await client.ai.listGuardrailProviders();
const provider  = await client.ai.getGuardrailProvider("provider_id");


// Create
const gp = await client.ai.createGuardrailProvider({
  name: "OpenAI Moderation",
  type: "openai",
  config: { api_key: "sk-..." },
});


// Test connectivity and list available models
const testResult = await client.ai.testGuardrailProvider(gp._id, { prompt: "test prompt" });
const models     = await client.ai.getGuardrailProviderModels(gp._id);


// Update and delete
await client.ai.updateGuardrailProvider(gp._id, { name: "OpenAI Moderation v2" });
await client.ai.deleteGuardrailProvider(gp._id);

RAG Files

Upload and manage files for Retrieval-Augmented Generation via the AI service.

const files = await client.ai.listRagFiles();
const file  = await client.ai.getRagFile("file_id");


// Upload
const formData = new FormData();
formData.append("file", fileBuffer, "knowledge.pdf");
const uploaded = await client.ai.uploadRagFile(formData);


await client.ai.deleteRagFile(uploaded._id);

AI Agents (via client.ai)

Additional AI agent read/update endpoints on the client.ai namespace. For full create/delete CRUD, use client.chatAi above.

// List agents from the accounts endpoint
const accountAgents = await client.ai.listAiAgents();
// List agents (agents endpoint)
const agents = await client.ai.listAgents();


// Get a single agent
const agent = await client.ai.getAiAgent("asst_abc");


// Check if a name is available before creating
const check = await client.ai.checkAiAgentName("Support Bot");
// check.available → true / false


// Patch only the instructions field
await client.ai.patchInstructions("asst_abc", {
  instructions: "You are a concise, helpful assistant.",
});

AI Agent Apps (via client.ai)

AI Agent Apps link an AI agent to a workflow or app configuration.

// Create
const app = await client.ai.createAiAgentApp({
  name: "Support App",
  workflow_name: "support_workflow_v1",
  assistant_id: "asst_abc",
  model_id: "Default",   // org-portable; "gpt-4o" only works in orgs whose system provider exposes it
  provider_id: "system",
});


// Update and delete
await client.ai.updateAiAgentApp(app._id, { name: "Support App v2" });
await client.ai.deleteAiAgentApp(app._id);


// Update only the workflow definition
await client.ai.updateAiAgentWorkflow(app._id, {
  workflow: { steps: [{ id: "step1", type: "llm" }] },
});

Tool Server

Verify that a custom tool server URL is reachable and returns a valid tool schema.

const result = await client.ai.verifyToolServer({ url: "https://my-tools.example.com/mcp" });
if (result.success) {
  console.log("Available tools:", result.tools);
}

Chat v2 — Streaming (SSE)

streamChat / stream_chat returns a raw Response over POST /ai-agent/v2/chat. The body shape depends on the agent’s streaming flag:

Agent streamingContent-TypeBody
true (recommended)text/event-streamVercel-AI-SDK UI-Message-Stream: data: {"type":"text-delta","delta":"..."} events
false (default for newly-created agents)text/plainFull reply as a single string — no SSE framing

Preferred: streamChatText / stream_chat_text

These convenience helpers wrap streamChat, parse the SSE event stream, and yield plain text deltas. They assume the agent was created with streaming: true.

for await (const chunk of client.aiAgent.streamChatText({
  id: "chat_id",
  assistant_id: "asst_abc",
  messages: [{ role: "user", content: "What can you do?" }],
})) {
  process.stdout.write(chunk);
}

Handling both streaming and non-streaming agents

When you don’t control how an agent was created, branch on Content-Type:

const body = {
  id: "chat_id",
  assistant_id: "asst_abc",
  messages: [{ role: "user", content: "What can you do?" }],
};


const res = await client.aiAgent.streamChat(body);
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);


const contentType = res.headers.get("content-type") ?? "";
let reply = "";


if (contentType.includes("text/event-stream")) {
  // streaming agent — re-parse via the SDK helper
  for await (const chunk of client.aiAgent.streamChatText(body)) {
    reply += chunk;
    process.stdout.write(chunk);   // render as it arrives
  }
} else {
  // non-streaming agent — body is the full reply
  reply = await res.text();
  process.stdout.write(reply);
}

Sub-agent Chat v2

Stream responses from a sub-agent and retrieve its conversation history.

const res = await client.aiAgent.streamSubAgentChat({
  assistant_id: "asst_sub",
  session_id: "sess_xyz",
  chat_id: "chat_id",
  messages: [{ role: "user", content: "Explain the data." }],
});


const history = await client.aiAgent.getSubAgentHistory({
  session_id: "sess_xyz",
  chat_id: "chat_id",
});

Prompt Suggestions

Fetch pre-built prompt suggestions for a given AI agent.

const suggestions = await client.aiAgent.getAgentPromptSuggestion("asst_abc");

Embeddings & Knowledge Base

Manage files used for Retrieval-Augmented Generation (RAG). Upload files first via client.boards.uploadFile (TypeScript) / client.boards.upload_file (Python), then trigger embedding processing.

// Trigger embedding processing for an uploaded file
await client.aiAgent.processEmbedding({ fileId: "file_abc" });


// List and inspect embedding files
const files   = await client.aiAgent.listEmbeddingFiles({ page: 1, limit: 20 });
const file    = await client.aiAgent.getEmbeddingFile("file_abc");
const preview = await client.aiAgent.previewEmbeddingFile({ file_id: "file_abc" });


// Update status and delete
await client.aiAgent.updateEmbeddingFileStatus("file_abc", "active");
await client.aiAgent.deleteEmbeddingFile("file_abc");


// Classify a file for RAG categorization
const classification = await client.aiAgent.classifyFile({ file_id: "file_abc" });

Data Board

Analyze sample documents (PDFs/images) to suggest a JSON schema suitable for Document AI agents.

const result = await client.aiAgent.suggestFieldTypes({
  fileUrls: [
    "https://cdn.imbrace.co/docs/invoice-1.pdf",
    "https://cdn.imbrace.co/docs/invoice-2.pdf",
  ],
});
// result.fields[i].suggestedType → "datetime" | "number" | "boolean" | ...

Parquet

Generate and manage Parquet columnar data files for analytics pipelines.

// Generate a Parquet file from JSON data
const result = await client.aiAgent.generateParquet({
  data: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }],
  fileName: "users",
  folderName: "exports",
});


const files = await client.aiAgent.listParquetFiles();
await client.aiAgent.deleteParquetFile("exports/users.parquet");

Distributed Tracing (Tempo)

Query Grafana Tempo traces emitted by the AI Agent service for observability and debugging.

// List recent traces
const traces = await client.aiAgent.getTraces({
  service:   "ai-agent",
  limit:     50,
  timeRange: 3600,     // seconds
  orgId:     "org_abc",
  details:   true,
});


// Inspect a single trace
const trace = await client.aiAgent.getTrace("trace_id_hex");


// Enumerate services, tags, and tag values
const services = await client.aiAgent.getTraceServices();
const tags     = await client.aiAgent.getTraceTags();
const values   = await client.aiAgent.getTraceTagValues("http.status_code");


// TraceQL search
const results = await client.aiAgent.searchTraceQL(
  `{ .service.name = "ai-agent" && .http.status = 500 }`
);

Chat Client

The Chat Client sub-API powers frontend applications (e.g. the embedded chat widget). For framework-level wiring (React singleton, Express auth proxy, etc.), see Integrations.

Auth

await client.aiAgent.verifyChatClientCredentials({ token: "tok_xxx" });
await client.aiAgent.registerChatClient({ name: "web-app", secret: "s3cr3t" });
const user = await client.aiAgent.getChatClientUser({ token: "tok_xxx" });

Chats

// Create a new chat session
await client.aiAgent.createClientChat({
  id:                     "chat_uuid",
  assistantId:            "asst_abc",
  organizationId:         "org_abc",
  userId:                 "user_xxx",
  selectedVisibilityType: "private",
  message: {
    id:        "msg_uuid",
    role:      "user",
    content:   "Hello!",
    createdAt: new Date().toISOString(),
    parts:     [{ type: "text", text: "Hello!" }],
  },
});


// List, read, update, delete chats
const chats = await client.aiAgent.listClientChats({
  organization_id: "org_abc",
  limit: 20,
});
const chat = await client.aiAgent.getClientChat("chat_id");
await client.aiAgent.updateClientChat("chat_id", { visibility: "private" });
await client.aiAgent.deleteClientChat("chat_id");
await client.aiAgent.deleteAllClientChats({ organization_id: "org_abc" });


// Auto-generate a title for the chat
await client.aiAgent.generateClientChatTitle("chat_id");


// Stream real-time chat status as SSE — returns raw Response
const statusStream = await client.aiAgent.streamClientChatStatus("chat_id");

Messages

await client.aiAgent.persistClientMessage({ chatId: "chat_id", content: "Hello" });
const messages = await client.aiAgent.listClientMessages("chat_id");
await client.aiAgent.deleteTrailingMessages("message_id");

Votes

const votes = await client.aiAgent.getVotes("chat_id");
await client.aiAgent.updateVote({ messageId: "msg_id", vote: "up" });

Documents (AI-generated artifacts)

await client.aiAgent.createDocument({ kind: "text", content: "Draft..." });


const doc        = await client.aiAgent.getDocument("doc_id");
const latest     = await client.aiAgent.getDocumentLatest("doc_id");
const pub        = await client.aiAgent.getDocumentPublic("doc_id");
const byKind     = await client.aiAgent.getDocumentLatestByKind({ kind: "text" });
const suggestion = await client.aiAgent.getDocumentSuggestions("doc_id");


await client.aiAgent.deleteDocument("doc_id");

Service info

Utility endpoints to check the AI Agent service status and version.

const config  = await client.aiAgent.getConfig();
const health  = await client.aiAgent.getHealth();          // summary
const details = await client.aiAgent.getHealth(true);      // detailed
const version = await client.aiAgent.getVersion();

Admin Guides

Access admin documentation hosted by the AI Agent service. Guide files are returned as raw binary streams (typically PDF).

const guides = await client.aiAgent.listAdminGuides();


// Download a specific guide — returns raw Response (PDF stream)
const response = await client.aiAgent.getAdminGuide("onboarding.pdf");
const blob = await response.blob();

Legacy v1 chat

The original REST chat endpoints persist conversation history without streaming. New code should use Chat v2 streaming above; v1 stays for backwards compatibility with existing chats.

// List chats for an organization
const chats = await client.aiAgent.listChats({
  organization_id: "org_abc",
  user_id: "user_123",
  limit: 20,
});


// Get a single chat (pass true to include messages)
const chat = await client.aiAgent.getChat("chat_id", true);


// Delete a chat
await client.aiAgent.deleteChat("chat_id", {
  organization_id: "org_abc",
  user_id: "user_123",
});