Workspace & Context

Overview

A workspace gives your agent a working environment - this could be files, API access, database connections, existing dashboards, or anything your agent needs to do its job.

Think of it as: The agent's "working space" - what it has access to when helping users.

What Is a Workspace?

A workspace can be:

Virtual files - Documents, code, data the agent can access
API connections - Your APIs the agent can call
Database access - Queries the agent can run
Existing dashboards - Your app/dashboard the agent works with
Custom environment - Anything you define

Powered by: Oblien Sandbox - built-in isolated environments

Types of Workspaces

Virtual File System

Agent has access to files (like a file system):

workspace: {
  app_id: 'my-project',
  files: {
    '/docs/api.md': 'API documentation content...',
    '/data/users.json': '{"users": [...]}'
  }
}

Use for: Document-based agents, code projects, data analysis

API Access

Agent can call your APIs:

workspace: {
  app_id: 'crm-workspace',
  apis: {
    baseUrl: 'https://api.yourapp.com',
    endpoints: ['/customers', '/orders', '/inventory']
  }
}

Use for: Agents that interact with your backend services

Database Connection

Agent can query databases:

workspace: {
  app_id: 'analytics-workspace',
  database: {
    type: 'postgres',
    connection: 'read-only-connection-string'
  }
}

Use for: Data analysis, reporting, querying

Existing Dashboard

Agent works within your app/dashboard:

workspace: {
  app_id: 'user-dashboard-123',
  type: 'dashboard',
  context: {
    userId: 'user-456',
    permissions: ['read', 'write'],
    currentView: '/analytics'
  }
}

Use for: Agents embedded in your application

Custom Environment

Define any environment:

workspace: {
  app_id: 'custom-env',
  type: 'custom',
  config: {
    // Whatever your agent needs
    tools: ['search', 'calculator'],
    data: { /* custom data */ }
  }
}

Use for: Specialized use cases

How to Set Workspace

When Creating Session (Core SDK)

Pass workspace config when creating sessions:

import { OblienChat } from 'oblien';

const chat = new OblienChat(client);

const session = await chat.createSession({
  agentId: process.env.AGENT_ID,
  namespace: req.user.id,
  workspace: {
    app_id: 'project-123',           // Unique workspace ID
    type: 'persistent',               // or 'ephemeral'
    // Your workspace config here
    files: { /* virtual files */ },
    apis: { /* API access */ },
    context: { /* custom context */ }
  }
});

Same app_id = Same workspace across sessions (persistent)

See Core SDK - Sessions for details.

In Agent Settings (Dashboard)

Configure default workspace for your agent:

Go to your agent in dashboard
Click Workspace tab
Set default workspace type
Configure permissions and access

Workspace Types

Ephemeral (Temporary)

What: Workspace exists only during the session
When deleted: After conversation ends
Use for: One-time tasks, temporary analysis

Example: User analyzes data → workspace created → work done → workspace deleted

Persistent

What: Workspace stays alive across sessions
When deleted: After X days or manually
Use for: Ongoing projects, user dashboards

Example: User's personal workspace → files persist between conversations

Same app_id across sessions = Same persistent workspace

Built-In: Oblien Sandbox

All workspaces run in Oblien Sandbox - our built-in isolated environment system:

Features:

Secure isolation (can't access other workspaces)
Resource limits (storage, CPU, memory)
Network access control
Permission management
Automatic cleanup

You don't manage infrastructure - just define what the workspace contains.

Use Cases

Document Agent with Virtual Files

Scenario: Agent helps users with company docs

workspace: {
  app_id: 'company-docs',
  files: {
    '/policies/leave.md': '...policy content...',
    '/guides/onboarding.md': '...guide content...',
    '/faqs/benefits.md': '...FAQ content...'
  }
}

Agent can search and reference these documents.

CRM Agent with API Access

Scenario: Agent queries your CRM

workspace: {
  app_id: 'crm-agent',
  apis: {
    baseUrl: 'https://api.yourcrm.com',
    auth: 'Bearer your-api-key',
    endpoints: {
      customers: '/api/customers',
      tickets: '/api/tickets'
    }
  }
}

Agent can fetch customer data, check ticket status, etc.

Analytics Agent with Database

Scenario: Agent runs analytics queries

workspace: {
  app_id: 'analytics',
  database: {
    type: 'postgres',
    readOnly: true,
    allowedTables: ['orders', 'customers', 'products']
  }
}

Agent can query data and generate reports.

Dashboard Agent

Scenario: Agent embedded in your app

workspace: {
  app_id: `dashboard-${userId}`,
  type: 'dashboard',
  context: {
    userId: userId,
    accountType: 'premium',
    currentView: req.body.currentPage,
    permissions: user.permissions
  }
}

Agent knows user's context and dashboard state.

Code Development Agent

Scenario: Agent helps build projects

workspace: {
  app_id: 'dev-project-456',
  type: 'sandbox',
  files: {
    '/src/app.js': 'existing code...',
    '/package.json': '{"dependencies": {}}'
  },
  permissions: {
    fileSystem: true,
    codeExecution: true,
    network: true
  }
}

Agent can read/write code, run tests, install packages.

Workspace Settings

Resource Limits

Storage: Disk space available
Memory: RAM for operations
CPU: Processing power
Network: Internet access

Configure in dashboard or per-session.

Permissions

Control what agents can do:

File System: Read, write, delete
Network: API calls, which domains
Execution: Run code, which languages
Database: Query access, read-only vs read-write

Retention

Ephemeral: Deleted after session
Persistent: Kept for X days (default: 30)

Configure per workspace type.

Security & Isolation

Oblien Sandbox

All workspaces run in isolated Oblien Sandbox:

Isolated - Can't access other workspaces
Secure - Can't access your system
Limited - Resource and permission controls
Monitored - Activity tracked

Safe: Even if agent misbehaves, it's contained.

Workspace usage
API calls made
Files accessed
Resource consumption

In Code

Track workspace activity:

// Monitor in your app
session.on('workspace_activity', (event) => {
  console.log('Agent action:', event.action);
});

See Chat SDK - Status Events for monitoring.

Best Practices

Choose Right Type

Use ephemeral for:

One-time analysis
Temporary tasks
No state needed

Use persistent for:

User projects
Ongoing work
State between sessions

Security

Provide minimum access:

Only APIs agent needs
Read-only when possible
Scoped permissions

Never expose:

User credentials
API secrets
Sensitive data directly

Performance

Keep workspaces lightweight:

Only necessary files
Limit API endpoints
Reasonable resource limits

Clean up:

Delete unused workspaces
Set appropriate retention
Monitor resource usage

Common Patterns

Per-User Workspace

Each user gets their own:

workspace: {
  app_id: `user-${userId}`,
  type: 'persistent',
  context: { userId, preferences }
}

Shared Workspace

Multiple users, same workspace:

workspace: {
  app_id: 'shared-docs',
  type: 'persistent',
  sharedAccess: true
}

Session-Specific

New workspace per session:

workspace: {
  app_id: `session-${sessionId}`,
  type: 'ephemeral'
}

Troubleshooting

Agent Can't Access Workspace

Check:

Workspace properly configured in session?
Agent has permissions?
Resource limits not exceeded?
APIs/services reachable?

Workspace Not Persisting

Check:

Type set to 'persistent'?
Same app_id across sessions?
Retention period not expired?
Not manually deleted?

Performance Issues

Check:

Workspace too large?
Too many API calls?
Resource limits appropriate?
Network latency?

Decide what your agent needs (files? APIs? dashboard context?)
Create workspace config
Pass it when creating sessions (Core SDK)
Test agent behavior
Monitor in Activity tab

Learn more:

Core SDK - Sessions - Passing workspace config
Tools - Enable agent actions
Context - Add knowledge
Integration - Complete example

On this page