SDK

FF-SDK

The client SDK for consuming FireFoundry agents. Call your deployed agents from any TypeScript/JavaScript application with full type safety and streaming support.

Installation:

npm install @firefoundry/sdk

Two SDKs, Two Purposes

@firefoundry/sdk (This SDK)

For consuming agents from your apps

- Call deployed agents via API
- Stream responses to your UI
- Manage conversations and sessions
- Works in browser and Node.js

@firefoundry/agent-sdk

For building agents

- Define bots, entities, workflows
- TypeScript decorators
- Platform integration
Learn more →

Why FF-SDK

Once your agents are deployed on FireFoundry, you need to call them from your applications. The FF-SDK provides a clean, type-safe interface for interacting with your agents from web apps, mobile apps, backend services, or anywhere JavaScript runs.

Get streaming responses for chat interfaces, manage conversation history automatically, and handle errors gracefully. The SDK works identically in browser and Node.js environments.

Basic usage - call an agent:

import { FireFoundry } from '@firefoundry/sdk';

const ff = new FireFoundry({
  apiKey: process.env.FF_API_KEY,
  environment: 'production'
});

// Call your deployed agent
const response = await ff.agent('support-bot').chat({
  message: 'How do I reset my password?'
});

console.log(response.content);
// → "To reset your password, go to Settings > Security..."

Streaming responses for real-time UI:

import { FireFoundry } from '@firefoundry/sdk';

const ff = new FireFoundry({ apiKey: process.env.FF_API_KEY });

// Stream response chunks as they arrive
const stream = await ff.agent('research-bot').stream({
  message: 'Summarize the latest AI news'
});

for await (const chunk of stream) {
  // Update UI as each chunk arrives
  process.stdout.write(chunk.content);
}

// Access full response and metadata when complete
console.log('\n\nSources:', stream.metadata.sources);

Manage conversation sessions:

import { FireFoundry } from '@firefoundry/sdk';

const ff = new FireFoundry({ apiKey: process.env.FF_API_KEY });
const agent = ff.agent('support-bot');

// Start a new conversation
const session = await agent.createSession({
  userId: 'user-123',
  metadata: { source: 'web-chat' }
});

// Messages in the same session share context
await session.chat({ message: 'I need help with my order' });
await session.chat({ message: 'It was order #456' });
await session.chat({ message: 'When will it arrive?' });
// Bot remembers the order number from earlier messages

// Later: resume an existing session
const resumed = await agent.getSession('session-id-here');
await resumed.chat({ message: 'Any update on that order?' });

React integration:

import { useAgent, useSession } from '@firefoundry/sdk/react';

function ChatWidget() {
  const agent = useAgent('support-bot');
  const { messages, sendMessage, isStreaming } = useSession(agent);

  return (
    <div>
      {messages.map(msg => (
        <Message key={msg.id} {...msg} />
      ))}

      <input
        onSubmit={(e) => sendMessage(e.target.value)}
        disabled={isStreaming}
      />
    </div>
  );
}

Real-Time Streaming

Stream responses token by token for responsive chat UIs. First token arrives fast, full response streams in progressively.

Type Safe

Full TypeScript support with inference. IDE autocomplete for agent names, methods, and response types.

Automatic Retries

Built-in retry logic with exponential backoff. Handles transient errors gracefully without crashing your app.

Session Management

Conversation context is managed automatically. Create sessions, resume them later, and maintain context across messages.

Works Everywhere

Node.js

Backend services

Browser

Web apps

React

Hooks included

Edge

Cloudflare, Vercel

Learn More

Full API Reference AgentSDK (for building agents) Back to Developer Ecosystem