typescript

@agentcontextos/sdk — TypeScript SDK

Official TypeScript/JavaScript client for the AgentContextOS RAG gateway. Works in Node 18+ and modern browsers — it uses the platform fetch and ReadableStream, with no runtime dependencies.

Install

npm install @agentcontextos/sdk
# or: pnpm add @agentcontextos/sdk

Quick start

import { AgentContextOSClient } from '@agentcontextos/sdk';

const rag = new AgentContextOSClient('http://localhost:8000', {
  tenantId: 'acme',
  principalId: 'svc',
});

// Retrieval-only
const hits = await rag.retrieve('How do I rotate signing keys?', { topK: 5 });

// Full RAG (optionally with an LLM answer)
const resp = await rag.query('How do I rotate signing keys?', { generate: true });
console.log(resp.answer?.text ?? resp.chunks.map((c) => c.content));

// OpenAI-compatible chat with retrieval pre-fetch
const chat = await rag.chat([{ role: 'user', content: 'Summarise our key-rotation policy' }]);
console.log(chat.choices[0]?.message.content);

Streaming (async iterators)

for await (const chunk of rag.streamChat([{ role: 'user', content: 'Explain HNSW' }])) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? '');
}

for await (const event of rag.streamAgent('Find the on-call runbook')) {
  console.log(event.kind, event.phase);
}
const result = await rag.agent('Find the on-call runbook'); // run to completion

Identity

Configure identity once; the SDK applies it the way each route expects (request body for query/retrieve/agent, headers for the rest):

• Dev / demo: { tenantId, principalId }.
• Production: { apiKey, tenantId } (sent as Authorization: Bearer …).

Per-call tenantId / principalId options override the client defaults.

Errors

Non-2xx responses reject with an ApiError subclass keyed by status: BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), RateLimitError (429), ServerError (5xx). Each carries .statusCode, .code, .requestId.

Development

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm test            # vitest
pnpm run build       # emit dist/

The hand-written types here mirror the committed dist/openapi.json and proto/rag.proto. See docs/reference/sdks.md.