TypeScript SDK for AgentOS HTTP API
npm install @worksofadam/agentos-sdk


TypeScript SDK for the AgentOS HTTP API. Run agents, teams, and workflows with streaming responses in under 5 lines of code.
``typescript
import { AgentOSClient } from '@worksofadam/agentos-sdk';
const client = new AgentOSClient({ apiKey: process.env.AGENTOS_API_KEY });
const stream = await client.agents.runStream('agent-id', { message: 'Hello!' });
for await (const event of stream) {
if (event.event === 'RunContent') console.log(event.content);
}
`
`bashnpm
npm install @worksofadam/agentos-sdk
Usage Examples
$3
List all agents:
`typescript
const client = new AgentOSClient({ apiKey: 'your-api-key' });
const agents = await client.agents.list();
console.log(agents);
`Run an agent (non-streaming):
`typescript
const result = await client.agents.run('agent-id', {
message: 'What is the weather today?',
sessionId: 'session-123',
userId: 'user-456'
});
console.log(result);
`Run an agent with streaming (iterator pattern):
`typescript
const stream = await client.agents.runStream('agent-id', {
message: 'Tell me a story',
sessionId: 'session-123'
});for await (const event of stream) {
switch (event.event) {
case 'RunStarted':
console.log('Run started:', event.run_id);
break;
case 'RunContent':
console.log('Content:', event.content);
break;
case 'RunCompleted':
console.log('Completed:', event.metrics);
break;
}
}
`Continue a paused agent run:
`typescript
// After agent requests tool execution
const toolResults = JSON.stringify([
{ tool_call_id: 'call_123', output: 'Tool result' }
]);const stream = await client.agents.continue('agent-id', 'run-id', {
tools: toolResults,
sessionId: 'session-123',
stream: true // default: true, set false for non-streaming
});
for await (const event of stream) {
console.log(event);
}
`Cancel a running agent:
`typescript
await client.agents.cancel('agent-id', 'run-id');
`$3
List all teams:
`typescript
const teams = await client.teams.list();
console.log(teams);
`Run a team with streaming (event emitter pattern):
`typescript
const stream = await client.teams.runStream('team-id', {
message: 'Analyze this data',
sessionId: 'session-123'
});await stream
.on('RunStarted', (event) => {
console.log('Team run started:', event.run_id);
})
.on('RunContent', (event) => {
console.log('Content:', event.content);
})
.on('RunCompleted', (event) => {
console.log('Metrics:', event.metrics);
})
.start();
`$3
List all workflows:
`typescript
const workflows = await client.workflows.list();
console.log(workflows);
`Run a workflow:
`typescript
const result = await client.workflows.run('workflow-id', {
message: 'Start the process',
sessionId: 'session-123'
});
console.log(result);
`$3
Create a new session:
`typescript
const session = await client.sessions.create({
userId: 'user-123',
agentId: 'agent-456',
sessionName: 'Customer Support Chat'
});
console.log(session.id);
`List sessions with filtering:
`typescript
const sessions = await client.sessions.list({
userId: 'user-123',
agentId: 'agent-456'
});
console.log(sessions);
`Get runs for a session:
`typescript
const runs = await client.sessions.getRuns('session-id');
console.log(runs);
`$3
List memories with filtering:
`typescript
const memories = await client.memories.list({
userId: 'user-123',
topics: ['preferences', 'history']
});
console.log(memories);
`Create a memory:
`typescript
const memory = await client.memories.create({
memory: 'User prefers dark mode',
userId: 'user-123',
topics: ['preferences']
});
console.log(memory);
`Search memories:
`typescript
const results = await client.memories.list({
userId: 'user-123',
query: 'dark mode'
});
console.log(results);
`$3
Upload a file to knowledge base:
`typescript
// From file path (Node.js only)
const content = await client.knowledge.upload({
file: '/path/to/document.pdf',
name: 'Product Documentation',
description: 'Latest product specs',
metadata: { version: '2.1' }
});// From Buffer
import { readFileSync } from 'fs';
const buffer = readFileSync('/path/to/document.pdf');
const content = await client.knowledge.upload({
file: buffer,
name: 'Product Documentation'
});
// From URL
const content = await client.knowledge.upload({
url: 'https://example.com/document.pdf',
name: 'External Document'
});
// From text content
const content = await client.knowledge.upload({
textContent: 'This is important information...',
name: 'Text Note',
description: 'Quick note'
});
`Upload multiple files:
`typescript
const files = [
'/path/to/doc1.pdf',
'/path/to/doc2.pdf'
];for (const filePath of files) {
await client.knowledge.upload({ file: filePath });
}
`Search knowledge base:
`typescript
const results = await client.knowledge.search('product features', {
searchType: 'hybrid', // 'vector' | 'keyword' | 'hybrid'
maxResults: 10,
filters: { category: 'documentation' }
});for (const result of results.data) {
console.log(result.content, result.score);
}
`Check upload processing status:
`typescript
const status = await client.knowledge.getStatus('content-id');
if (status.status === 'completed') {
console.log('Processing complete');
} else if (status.status === 'processing') {
console.log('Still processing...');
}
`$3
List traces with filtering:
`typescript
const traces = await client.traces.list({
run_id: 'run-123',
session_id: 'session-456',
starting_date: '2024-01-01',
ending_date: '2024-01-31'
});
console.log(traces);
`$3
Get metrics:
`typescript
const metrics = await client.metrics.get({
session_id: 'session-123',
starting_date: '2024-01-01',
ending_date: '2024-01-31'
});
console.log(metrics);
`Refresh metrics:
`typescript
await client.metrics.refresh();
`Streaming
The SDK provides two patterns for consuming streaming responses:
$3
Best for sequential processing of events:
`typescript
const stream = await client.agents.runStream('agent-id', {
message: 'Hello!'
});for await (const event of stream) {
// Type-safe event handling
switch (event.event) {
case 'RunStarted':
console.log('Started:', event.run_id);
break;
case 'RunContent':
process.stdout.write(event.content);
break;
case 'RunCompleted':
console.log('\nDone! Metrics:', event.metrics);
break;
case 'MemoryUpdateStarted':
console.log('Updating memories...');
break;
case 'MemoryUpdateCompleted':
console.log('Memories updated');
break;
}
}
`$3
Best for parallel event handling with multiple listeners:
`typescript
const stream = await client.teams.runStream('team-id', {
message: 'Process this data'
});await stream
.on('RunStarted', (event) => {
console.log('Run ID:', event.run_id);
})
.on('RunContent', (event) => {
// Build up response content
responseBuffer += event.content;
})
.on('RunCompleted', (event) => {
console.log('Final metrics:', event.metrics);
saveMetrics(event.metrics);
})
.on('MemoryUpdateCompleted', (event) => {
console.log('Memories synced');
})
.start();
`$3
All streams support cancellation via AbortController:
`typescript
const stream = await client.agents.runStream('agent-id', {
message: 'Long running task...'
});// Cancel after 5 seconds
setTimeout(() => {
stream.controller.abort();
console.log('Stream cancelled');
}, 5000);
try {
for await (const event of stream) {
console.log(event);
}
} catch (error) {
if (error.name === 'AbortError') {
console.log('Stream was cancelled');
}
}
`File Uploads
The SDK supports multiple file input formats for maximum flexibility:
$3
`typescript
import type { FileInput, Image, Audio, Video, FileType } from '@worksofadam/agentos-sdk';// FileInput accepts:
// - string: File path (Node.js only - converted to ReadStream)
// - Buffer: In-memory binary data
// - ReadStream: Node.js file stream
// - Blob: Browser Blob or Node.js Blob
// - File: Browser File object
`$3
`typescript
// Single image from file path (Node.js only)
const result = await client.agents.run('agent-id', {
message: 'What is in this image?',
images: ['/path/to/photo.jpg']
});// Multiple files from Buffers
import { readFileSync } from 'fs';
const image1 = readFileSync('/path/to/photo1.jpg');
const image2 = readFileSync('/path/to/photo2.jpg');
const result = await client.agents.run('agent-id', {
message: 'Compare these images',
images: [image1, image2]
});
// Mixed media types
const result = await client.agents.run('agent-id', {
message: 'Analyze this multimedia content',
images: ['/path/to/screenshot.png'],
audio: [audioBuffer],
videos: ['/path/to/demo.mp4'],
files: ['/path/to/document.pdf']
});
`$3
For advanced use cases, use the
normalizeFileInput utility:`typescript
import { normalizeFileInput } from '@worksofadam/agentos-sdk';// Normalize any file input to FormData-compatible format
const normalized = await normalizeFileInput('/path/to/file.pdf', 'document.pdf');
// Returns: { data: Blob | ReadStream, filename: string }
`$3
Node.js:
- All file input types supported
- File paths converted to
ReadStream for efficient streaming
- Buffer converted to Blob for FormData compatibilityBrowser (future support):
- File paths NOT supported (no filesystem access)
-
Blob and File objects work natively
- Buffer converted to Blob
- ReadStream NOT available in browsersError Handling
The SDK provides typed error classes for precise error handling:
`typescript
import {
APIError,
AuthenticationError,
BadRequestError,
NotFoundError,
RateLimitError,
InternalServerError,
RemoteServerUnavailableError,
UnprocessableEntityError
} from '@worksofadam/agentos-sdk';try {
const result = await client.agents.run('agent-id', {
message: 'Hello!'
});
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key:', error.message);
} else if (error instanceof NotFoundError) {
console.error('Agent not found:', error.message);
} else if (error instanceof RateLimitError) {
console.error('Rate limit exceeded. Retry after:', error.message);
} else if (error instanceof BadRequestError) {
console.error('Invalid request:', error.message);
} else if (error instanceof InternalServerError) {
console.error('Server error:', error.message);
console.error('Request ID:', error.requestId);
} else if (error instanceof APIError) {
console.error('API error:', error.status, error.message);
} else {
console.error('Network error:', error);
}
}
`$3
All API errors extend
APIError and include:-
status: HTTP status code
- message: Error message from API
- requestId: X-Request-ID header value (for support)
- body: Raw response bodyTypeScript
The SDK is written in TypeScript and provides full type safety:
`typescript
import type {
AgentOSClient,
RunOptions,
StreamRunOptions,
AgentRunEvent,
components,
paths
} from '@worksofadam/agentos-sdk';// All resource methods are fully typed
const result = await client.agents.run('agent-id', {
message: 'Hello',
sessionId: 'optional-session',
// TypeScript will error if you pass invalid options
});
// Event types are discriminated unions for type-safe handling
for await (const event of stream) {
if (event.event === 'RunContent') {
// TypeScript knows event.content exists here
console.log(event.content);
}
}
// Access generated OpenAPI types
type AgentResponse = components['schemas']['AgentResponse'];
type ListAgentsPath = paths['/agents']['get'];
`$3
The SDK generates TypeScript types directly from the AgentOS OpenAPI specification:
- Run
npm run generate:types to regenerate types from openapi.json
- Types are committed to git in src/generated/types.ts
- All resource methods use generated types for request/response bodiesAPI Reference
$3
Constructor:
`typescript
new AgentOSClient(options: AgentOSClientOptions)
`Options:
-
apiKey?: string - API key for authentication (can also use AGENTOS_API_KEY env var)
- baseUrl?: string - Base URL for API (default: https://api.agno.com)
- timeout?: number - Request timeout in milliseconds (default: 60000)
- maxRetries?: number - Maximum retry attempts (default: 3)Methods:
-
getConfig(): Promise - Get server configuration
- health(): Promise - Check API health status$3
All resource operations are accessed via namespaced properties:
-
client.agents - Agent operations
- client.teams - Team operations
- client.workflows - Workflow operations
- client.sessions - Session management
- client.memories - Memory operations
- client.knowledge - Knowledge base operations
- client.traces - Trace retrieval
- client.metrics - Metrics retrieval$3
Most resources support these methods:
-
list(options?) - List all resources
- get(id) - Get resource by ID
- run(id, options) - Execute resource (non-streaming)
- runStream(id, options) - Execute resource (streaming)
- continue(id, runId, options) - Continue paused execution
- cancel(id, runId) - Cancel running executionSee TypeScript types for complete method signatures and options.
Requirements
- Node.js 18.0.0 or higher
- Note:
fetch is experimental in Node.js 18, stable in Node.js 21+
- For Node.js 18, consider using --experimental-fetch` flag or upgrade to Node.js 21+MIT License - see LICENSE file for details.
---
For more information, visit the AgentOS Documentation.