TypeScript SDK Overview

The Erdo TypeScript SDK enables you to integrate Erdo’s AI agents directly into your applications. Whether you’re building a Next.js app, a Node.js backend, or a React frontend, the SDK provides everything you need to message agents and render their results.

Packages

Package	Description
`@erdoai/server`	Server-side client for tokens, threads and messaging
`@erdoai/ui`	React components for rendering agent results

Installation

npm install @erdoai/server @erdoai/ui

yarn add @erdoai/server @erdoai/ui

pnpm add @erdoai/server @erdoai/ui

Quick Start

1. Create an API Token

Get your API token from the Erdo dashboard.

2. Send a Message to an Agent

Agents run inside threads. Your server mints a scoped token for an external user, then uses it to create a thread and send messages.

import { ErdoClient } from '@erdoai/server';

const server = new ErdoClient({
  authToken: process.env.ERDO_AUTH_TOKEN,
});
const { token } = await server.createToken({
  externalUserId: 'server-job',
  expiresInSeconds: 3600,
});
const client = new ErdoClient({ token });

const thread = await client.createThread({ name: 'Analysis' });
const events = await client.sendMessageAndWait(thread.id, { content: 'What were our top products last month?' });

console.log('Received', events.length, 'events');

3. Stream Results

For real-time updates, use streaming:

const thread = await client.createThread({ name: 'Analysis' });
for await (const event of client.sendMessage(thread.id, { content: 'Analyze our sales data' })) {
  switch (event.type) {
    case 'content':
      console.log('New content:', event.payload);
      break;
    case 'status':
      console.log('Status:', event.payload);
      break;
    case 'done':
      console.log('Complete!');
      break;
  }
}

4. Render Results in React

Never expose your API key to the browser. Use one of two secure patterns: ephemeral tokens or proxy streaming.

Option A: Ephemeral Tokens (Recommended) Your backend creates a short-lived, scoped token. The frontend uses it to stream directly from the Erdo API.

// app/api/authorize/route.ts (SERVER)
import { ErdoClient } from '@erdoai/server';

const client = new ErdoClient({ authToken: process.env.ERDO_AUTH_TOKEN });

export async function POST(request: Request) {
  const { userId } = await request.json();
  // Add your own RBAC logic here
  const { token, tokenId, expiresAt } = await client.createToken({
    externalUserId: userId,
    expiresInSeconds: 3600,
  });
  return Response.json({ token, tokenId, expiresAt });
}

// app/page.tsx (CLIENT)
'use client';
import { Content } from '@erdoai/ui';

function ChatInterface() {
  const [contents, setContents] = useState([]);

  const handleSubmit = async (query: string) => {
    // 1. Get ephemeral token from your backend
    const { token } = await fetch('/api/authorize', {
      method: 'POST',
      body: JSON.stringify({ userId: 'user_123' }),
    }).then(r => r.json());

    // 2. Send the message to a thread; the SDK streams directly from the Erdo API
    const client = new ErdoClient({ token });
    const thread = await client.createThread({ name: 'Analysis' });
    for await (const event of client.sendMessage(thread.id, { content: query })) {
      // 3. Render results (see integration docs for the full streaming example)
    }
  };

  return (
    <div>
      {contents.map((item, i) => <Content key={i} content={item} />)}
    </div>
  );
}

Option B: Proxy Streaming Your backend proxies the stream. The API key never leaves your server.

// app/api/messages/route.ts (SERVER)
import { ErdoClient } from '@erdoai/server';

const server = new ErdoClient({ authToken: process.env.ERDO_AUTH_TOKEN });

export async function POST(request: Request) {
  const { userId, threadId, content } = await request.json();
  const { token } = await server.createToken({ externalUserId: userId });
  const client = new ErdoClient({ token });

  const stream = new ReadableStream({
    async start(controller) {
      for await (const event of client.sendMessage(threadId, { content })) {
        controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(event)}\n\n`));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { 'Content-Type': 'text/event-stream' },
  });
}

See Integration Patterns for complete examples of both approaches.

Use Cases

Embed Data Analysis

Add AI-powered data analysis to your existing application:

// User asks a question in your app
const thread = await client.createThread({ name: 'Analysis' });
const events = await client.sendMessageAndWait(thread.id, { content: userQuestion });

// Render charts and insights

AI Tool in Chat Applications

Use Erdo as a tool alongside your LLM for data-intensive queries:

// When your LLM detects a data question, delegate to Erdo
if (isDataQuestion(userMessage)) {
  const thread = await client.createThread({ name: 'Analysis' });
  const events = await client.sendMessageAndWait(thread.id, { content: userMessage });
  // Return rich visualizations to the user
}

Automated Reporting

Generate reports programmatically:

const thread = await client.createThread({ name: 'Analysis' });
const events = await client.sendMessageAndWait(thread.id, { content: 'Generate a weekly sales report' });

Environment Variables

Configure the SDK using environment variables:

Variable	Description	Default
`ERDO_AUTH_TOKEN`	Your Erdo API key	Required
`ERDO_ENDPOINT`	API endpoint	`https://api.erdo.ai`

// Uses environment variables automatically
const client = new ErdoClient();

Next Steps

Client Reference - Detailed API documentation
UI Components - React component reference
Integration Patterns - Vercel AI SDK, Next.js patterns

Platform API

API Reference

Build apps

Python SDK

TypeScript SDK

TypeScript SDK Overview

TypeScript SDK Overview

Packages

Installation

Quick Start

1. Create an API Token

2. Send a Message to an Agent

3. Stream Results

4. Render Results in React

Use Cases

Embed Data Analysis

AI Tool in Chat Applications

Automated Reporting

Environment Variables

Next Steps

​TypeScript SDK Overview

​Packages

​Installation

​Quick Start

​1. Create an API Token

​2. Send a Message to an Agent

​3. Stream Results

​4. Render Results in React

​Use Cases

​Embed Data Analysis

​AI Tool in Chat Applications

​Automated Reporting

​Environment Variables

​Next Steps

TypeScript SDK Overview

Packages

Installation

Quick Start

1. Create an API Token

2. Send a Message to an Agent

3. Stream Results

4. Render Results in React

Use Cases

Embed Data Analysis

AI Tool in Chat Applications

Automated Reporting

Environment Variables

Next Steps