Agents

Ship Agents in 3 Steps

Oblien handles all infrastructure - users, sessions, rate limits, storage, tokens. You just integrate.

Total integration time: 5 minutes

What You DON'T Need

  • ❌ User management system
  • ❌ Session storage (Redis, database)
  • ❌ Rate limiting logic
  • ❌ Guest identification code
  • ❌ Token generation/validation
  • ❌ WebSocket server setup

We manage all of that. You just use two SDKs:

Backend: Core SDK - Creates sessions
Frontend: Chat SDK - Displays chat UI

How It Works (Fully Managed)

┌──────────────────────────────────────────────┐
│         Your Backend (5 lines of code)        │
│                                              │
│  Core SDK                                   │
│  → chat.createSession()                     │
│  → Returns token                            │
└──────────────────────────────────────────────┘
                    ↓ token
┌──────────────────────────────────────────────┐
│       Your Frontend (3 lines of code)        │
│                                              │
│  Chat SDK                                   │
│  → <ChatProvider authConfig={token}>        │
│  → <ChatPanel />                            │
└──────────────────────────────────────────────┘
                    ↓ chat
┌──────────────────────────────────────────────┐
│       Oblien Platform (We Manage This)       │
│                                              │
│  ✅ User tracking (auth + guests)            │
│  ✅ Session storage (NodeCache/Redis)        │
│  ✅ Rate limiting (per user/guest)           │
│  ✅ Guest identification (IP + fingerprint)  │
│  ✅ Token generation (JWT)                   │
│  ✅ Agent execution                          │
│  ✅ Tool management                          │
│  ✅ Workspace isolation                      │
└──────────────────────────────────────────────┘

You write 8 lines total. We handle everything else.

Before You Start

You need 3 things from your dashboard:

1. Create API Credentials

Go to Settings → API Credentials → Create API Key

You'll get:

  • Client ID: oblien_xxx...
  • Client Secret: sk_xxx...

⚠️ Save the secret immediately - it's only shown once!

2. Get Your Agent ID

Go to Agents → Select your agent → Copy the Agent ID

Format: agent-xxx or unique identifier shown in agent details

3. Set Environment Variables

# .env
OBLIEN_API_KEY=oblien_your_client_id
OBLIEN_API_SECRET=sk_your_client_secret
AGENT_ID=agent-your-agent-id

Never commit these to git!

Step-by-Step Integration

Step 1: Install Core SDK (Backend)

npm install oblien

Step 2: Backend Code (5 lines)

Create an endpoint that returns session tokens:

// backend/routes/session.ts
import express from 'express';
import { OblienClient, OblienChat } from 'oblien';

const router = express.Router();

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const chat = new OblienChat(client);

// For authenticated users
router.post('/session/create', requireAuth, async (req, res) => {
  const { agentId } = req.body;
  
  const session = await chat.createSession({
    agentId,
    namespace: req.user.id,  // Your user ID
    workspace: {
      app_id: 'my-app',
      user: {
        name: req.user.name,
        email: req.user.email
      }
    }
  });
  
  res.json(session);
});

// For anonymous users
router.post('/session/guest', async (req, res) => {
  const { agentId, fingerprint } = req.body;
  const ip = req.ip;
  
  const session = await chat.createGuestSession({
    ip,
    fingerprint,
    agentId
  });
  
  res.json(session);
});

export default router;

That's it for backend. No user tables, no Redis, no session storage code.

→ Complete Core SDK docs - Sessions, guests, framework examples

Step 3: Install Chat SDK (Frontend)

npm install react-chat-agent

Step 4: Frontend Code (3 lines)

Add chat UI to your app:

// frontend/components/Chat.tsx
'use client';

import { useState, useEffect } from 'react';
import { ChatProvider, ChatPanel, useForwarding, useStatusSubscription } from 'react-chat-agent';
import 'react-chat-agent/ui.css';

export function AgentChat() {
  const [authConfig, setAuthConfig] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    createSession();
  }, []);

  const createSession = async () => {
    try {
      const res = await fetch('/api/session/create', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          agentId: 'your-agent-id'
        })
      });
      
      const session = await res.json();
      
      setAuthConfig({
        sessionId: session.sessionId,
        accessToken: session.token
      });
    } catch (error) {
      console.error('Failed to create session:', error);
    } finally {
      setLoading(false);
    }
  };

  if (loading) return <div>Loading...</div>;
  if (!authConfig) return <div>Failed to connect</div>;

  return (
    <ChatProvider authConfig={authConfig}>
      <ChatPanel onCreateSession={createSession} />
    </ChatProvider>
  );
}

That's it for frontend. Chat is live.

→ Complete Chat SDK docs - Components, hooks, agent control, customization

Step 5: Ship

You're done. Deploy your app.

What you shipped:

  • ✅ Chat interface with your agent
  • ✅ User management (authenticated + guests)
  • ✅ Session management
  • ✅ Rate limiting
  • ✅ Security (tokens, API keys)

Infrastructure managed: 100%

Complete Example

Backend + Frontend Together

Here's a complete integration showing both parts:

Let agents control your application:

'use client';

import { useState } from 'react';
import { ChatProvider, ChatCore, ChatInput, useForwarding, useStatusSubscription } from 'react-chat-agent';
import MonacoEditor from '@monaco-editor/react';

export function CodeEditor() {
  const [authConfig, setAuthConfig] = useState(null);
  const [code, setCode] = useState('');
  const [status, setStatus] = useState('idle');

  // Agent writes code → Update editor
  useForwarding('write_code', (incrementalText, fullText) => {
    setCode(fullText);
  }, {
    mode: 'replace',  // Don't show in chat
    animated: false   // Instant updates
  });

  // Monitor tool execution
  useStatusSubscription('write_code', (statusData) => {
    setStatus(statusData.status.state);
    
    if (statusData.statusType === 'finished') {
      // Auto-format when done
      formatCode(code);
    }
  });

  return (
    <ChatProvider authConfig={authConfig}>
      <div className="flex h-screen">
        {/* Chat Interface */}
        <div className="w-1/2 flex flex-col">
          <ChatCore className="flex-1" />
          <ChatInput />
        </div>
        
        {/* Code Editor */}
        <div className="w-1/2 border-l">
          <div className="status-bar">
            Status: {status}
          </div>
          <MonacoEditor
            value={code}
            language="typescript"
            theme="vs-dark"
          />
        </div>
      </div>
    </ChatProvider>
  );
}

This example shows how agents can control your app - the code editor updates as the agent writes code.

→ More agent control examples

Quick Reference

Backend Quick Reference

// Core SDK - Server side
import { OblienClient, OblienChat } from 'oblien';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const chat = new OblienChat(client);
const session = await chat.createSession({ agentId, namespace: userId });
// Returns token to frontend

→ Full Core SDK docs - Sessions, guests, all frameworks

Frontend Quick Reference

// Chat SDK - Client side
import { ChatProvider, ChatPanel } from 'react-chat-agent';

<ChatProvider authConfig={{ sessionId, accessToken }}>
  <ChatPanel />
</ChatProvider>

→ Full Chat SDK docs - Components, hooks, agent control

What to Read

If You're Implementing Backend

Read Core SDK documentation →

  • Session management
  • Guest handling
  • Framework examples (Express, Next.js, etc.)
  • API reference

If You're Implementing Frontend

Read Chat SDK documentation →

  • Components and hooks
  • Agent control (forwarding)
  • Status monitoring
  • Styling and customization

If You Need Both

  1. Read Core SDK for backend setup
  2. Read Chat SDK for frontend setup
  3. Come back to this page for the complete flow

Complete Example with Credentials

Get Credentials from Dashboard

1. API Credentials (Settings):

Client ID: oblien_a1b2c3d4...
Client Secret: sk_x1y2z3a4...

2. Agent ID (Your Agent):

Agent ID: agent-12345

Backend Setup

Install and configure:

import { OblienClient, OblienChat } from 'oblien';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const chat = new OblienChat(client);

// API endpoint
app.post('/api/session/create', async (req, res) => {
  const session = await chat.createSession({
    agentId: req.body.agentId,
    namespace: req.user.id  // Your user ID
  });
  
  res.json(session); // { sessionId, token }
});

→ Detailed backend guide

Step 3: Frontend Setup

Use token to enable chat:

import { ChatProvider, ChatPanel } from 'react-chat-agent';
import 'react-chat-agent/ui.css';

function App() {
  const [authConfig, setAuthConfig] = useState(null);

  // Get token from your backend
  useEffect(() => {
    fetch('/api/session/create', {
      method: 'POST',
      body: JSON.stringify({ agentId: 'your-agent-id' })
    })
      .then(res => res.json())
      .then(session => {
        setAuthConfig({
          sessionId: session.sessionId,
          accessToken: session.token
        });
      });
  }, []);

  if (!authConfig) return <div>Loading...</div>;

  return (
    <ChatProvider authConfig={authConfig}>
      <ChatPanel />
    </ChatProvider>
  );
}

→ Detailed frontend guide

That's It

You're done! Your agent is now integrated. The frontend chats directly with Oblien using the token.

Adding Agent Control

Let agents control your app using hooks:

import { useForwarding, useStatusSubscription } from 'react-chat-agent';

function MyApp() {
  // Agent updates your code editor
  useForwarding('write_code', (code) => {
    editor.setValue(code);
  });

  // Monitor agent actions
  useStatusSubscription('tool_call', (status) => {
    console.log('Tool:', status.tool_name);
  });

  return <YourApp />;
}

→ Agent control guide

Documentation

Backend (Core SDK)

Core SDK → - Server-side SDK

Frontend (Chat SDK)

Chat SDK → - Client-side SDK

Need Help?

Creating Agents

Learn how to create and manage AI agents on the Oblien platform

Agent Instructions

Configure agent behavior with custom prompts and instructions using a rich text editor

On this page

Ship Agents in 3 Steps
What You DON'T Need
How It Works (Fully Managed)
Before You Start
1. Create API Credentials
2. Get Your Agent ID
3. Set Environment Variables
Step-by-Step Integration
Step 1: Install Core SDK (Backend)
Step 2: Backend Code (5 lines)
Step 3: Install Chat SDK (Frontend)
Step 4: Frontend Code (3 lines)
Step 5: Ship
Complete Example
Backend + Frontend Together
Quick Reference
Backend Quick Reference
Frontend Quick Reference
What to Read
If You're Implementing Backend
If You're Implementing Frontend
If You Need Both
Complete Example with Credentials
Get Credentials from Dashboard
Backend Setup
Step 3: Frontend Setup
That's It
Adding Agent Control
Documentation
Backend (Core SDK)
Frontend (Chat SDK)
Need Help?