Getting Started

This example demonstrates how to use the open-agents-builder-client to connect to the Open Agents Builder API. The API documentation can be found here.

Step 1: Create an API Key

To create an API key, follow the instructions here.

Step 2: Install the npm Packages

Install the required npm packages:

yarn add open-agents-builder-client zod nanoid dotenv
yarn add -D @types/node typescript

Step 3: Set the Required Environment Variables

Set the following environment variables in your project:

• DATABASE_ID_HASH: Your database ID hash (optional)
• OPEN_AGENTS_BUILDER_API_KEY: Your API key (required)
• AGENT_ID: Your agent ID (required for chat examples)

You can set these variables in a .env file at the root of your project:

DATABASE_ID_HASH=your_database_id_hash
OPEN_AGENTS_BUILDER_API_KEY=your_api_key
AGENT_ID=your_agent_id

Example Usage

Here are several examples showing how to use the client:

Basic Setup

import { config } from 'dotenv';
import { OpenAgentsBuilderClient } from "open-agents-builder-client";

// Load environment variables from .env file
config();

const client = new OpenAgentsBuilderClient({
    baseUrl: "https://app.openagentsbuilder.com",  // optional, defaults to this if omitted
    databaseIdHash: process.env.DATABASE_ID_HASH ?? '',  // optional, defaults to this if omitted
    apiKey: process.env.OPEN_AGENTS_BUILDER_API_KEY ?? ''  // required
});

Example 1: Basic Chat with Streaming

import { ChatMessage } from "open-agents-builder-client";

async function basicChat() {
    const messages: ChatMessage[] = [
        { role: "user", content: "What is the capital of France?" }
    ];

    try {
        for await (const chunk of client.chat.streamChat(messages, {
            agentId: process.env.AGENT_ID!
        })) {
            if (chunk.type === 'text') {
                process.stdout.write(chunk.content);
            }
        }
    } catch (error) {
        console.error("Error:", error);
    }
}

Example 2: Chat with Attachments

import * as fs from 'fs';

async function chatWithAttachments() {
    const messages: ChatMessage[] = [
        {
            role: "user",
            content: "What can you tell me about this image?",
            experimental_attachments: [
                {
                    name: "screenshot.png",
                    contentType: "image/png",
                    url: "https://example.com/image.png"
                },
                {
                    name: "sample.pdf",
                    file: "./sample.pdf" // Local file path
                }
            ]
        }
    ];

    try {
        for await (const chunk of client.chat.streamChat(messages, {
            agentId: process.env.AGENT_ID!
        })) {
            if (chunk.type === 'text') {
                process.stdout.write(chunk.content);
            }
        }
    } catch (error) {
        console.error("Error:", error);
    }
}

Example 3: Maintaining Conversation History

import { nanoid } from 'nanoid';

async function conversationWithHistory() {
    const sessionId = nanoid();
    const messages: ChatMessage[] = [
        { role: "user", content: "Let's talk about space exploration." }
    ];

    try {
        // First message
        for await (const chunk of client.chat.streamChat(messages, {
            agentId: process.env.AGENT_ID!,
            sessionId: sessionId
        })) {
            if (chunk.type === 'text') {
                process.stdout.write(chunk.content);
            }
        }

        // Continue conversation
        const followUpMessages: ChatMessage[] = [
            { role: "user", content: "Tell me more about Mars missions." }
        ];

        for await (const chunk of client.chat.streamChat(followUpMessages, {
            agentId: process.env.AGENT_ID!,
            sessionId: sessionId
        })) {
            if (chunk.type === 'text') {
                process.stdout.write(chunk.content);
            }
        }
    } catch (error) {
        console.error("Error:", error);
    }
}

Running the Examples

To run the examples:

yarn build
yarn start

For more detailed examples, check the src/index.ts file in this repository.