@uptiqai/agent-sdk

TypeScript SDK for running Uptiq agents. Isomorphic — the same package works in a Node backend and in the browser.

Install

npm install @uptiqai/agent-sdk

Usage

import { AgentClient } from '@uptiqai/agent-sdk';

// Node (server-to-server) — the secret is safe server-side.
const client = new AgentClient({
    apiKey: process.env.AGENT_API_KEY!,
    apiSecret: process.env.AGENT_API_SECRET!,
    baseUrl: 'https://api.example.com'
});

// Browser — never ship the secret; use a domain-whitelisted widget key.
// const client = new AgentClient({ widgetKey: '...', baseUrl: 'https://api.example.com' });

Upload documents

const documents = await client.documents.upload({
    agentId: 'precision-loan-guide',
    files: [{ fileName: 'rates.pdf', mimeType: 'application/pdf', data: fileOrBufferOrBase64 }]
});

Already have a signed URL? Skip the upload round-trip and pass it straight into run:

await client.agents.run({
    agentId,
    query: 'Compare a 15-year and 30-year fixed mortgage.',
    documents: [{ signedUrl, fileName: 'rates.pdf', mimeType: 'application/pdf' }]
});

Run an agent

// sync — blocks and returns the result
const run = await client.agents.run({
    agentId,
    query: 'Compare a 15-year and 30-year fixed mortgage.',
    payload: { creditScore: 720 },
    documents,               // refs from documents.upload()
    uid: 'user_123',
    executionMode: 'sync'
});
console.log(run.result?.content);

// async — returns immediately; the result is delivered to your webhook(s)
const { executionId } = await client.agents.run({
    agentId,
    query: 'Summarize the attached mortgage doc.',
    documents,
    executionMode: 'async',
    webhooks: [
        { url: 'https://my-app.example.com/agent-callback', metadata: { orderId: '123' } }
    ]
});

webhooks is an array of { url, metadata? }; the backend POSTs the execution result to each url, echoing your metadata back on the payload. Attach documents by passing the refs from documents.upload() (or { signedUrl } / { documentId }) as documents.

Conversations

const { conversations, total } = await client.conversations.list({ agentId, page: 1, pageSize: 20 });
const conversation = await client.conversations.getConversation({ agentId, executionId });

Errors

Every failure is a typed subclass of AgentSDKError (AuthenticationError, NotFoundError, RateLimitError, BadRequestError, InternalServerError, APIConnectionError) carrying .status, .headers, and .body.

import { AuthenticationError } from '@uptiqai/agent-sdk';

try {
    await client.agents.run({ agentId, query });
} catch (error) {
    if (error instanceof AuthenticationError) {
        // bad credentials
    }
}

Notes

• Realtime/streaming and async result-polling are not yet supported.
• OpenAI-compatible mode is coming soon.
• Auth is sent using the native headers: x-api-key + x-api-key-secret (server), or x-widget-key (browser).