Virtual Workers

Virtual team members for your organization. AI agents with defined roles, institutional knowledge, specialized skills, and the ability to learn and improve over time. It's the difference between opening a fresh AI chat session and working with a colleague who knows your company, your codebase, and your engineering standards.

Why It Matters

Every time you open a fresh AI chat session, you start from zero. The AI doesn't know your company, your architecture, your coding standards, or the decisions your team made last month. You spend half the conversation providing context before you can get real work done.

A Virtual Worker is different. It's a virtual team member—a managed AI agent with a defined role, institutional knowledge, specialized skills, and the ability to learn and improve over time. Think of it as the difference between hiring a contractor who knows nothing about your business and working with a colleague who's been on the team for months.

The underlying coding agent—Claude Code, Codex, Gemini CLI, OpenCode, or FireFoundry's own coding assistant—is just the execution engine. The raw capability to read code, reason about problems, and produce output. A Virtual Worker wraps that engine with everything needed to make it effective in your organization: identity, knowledge, skills, and continuous learning.

Key Capabilities

• Role & Identity: Workers have a defined role, personality, and behavioral guidelines—they're not generic AI, they're specific team members with a point of view
• Institutional Knowledge: A git-backed knowledge base gives each worker company context, engineering guidelines, architecture docs, and tribal knowledge
• Continuous Learning: Workers capture what they learn at session end, write learning documents to their knowledge repo, and create PRs for human review—each session makes the next one better
• Persistent Workspace: Sessions can be suspended and resumed automatically—workspaces persist between requests so workers pick up where they left off
• Multi-Engine Support: Choose from Claude Code, Codex, Gemini CLI, OpenCode, or FireFoundry's built-in coding assistant—same API regardless of engine
• Full Telemetry: Every prompt, response, file operation, and token count is logged with timing and correlation data

How It Works

You define who the worker is—their role, personality, and instructions. You give them knowledge—a git repo with company context, guidelines, and domain expertise. You equip them with skills—tools and platform integrations. The execution engine (Claude Code, Codex, Gemini CLI, OpenCode, or FireFoundry's built-in assistant) is just the runtime—interchangeable and transparent to your code.

Over time, auto-learning makes workers smarter. At the end of each session, workers capture what they learned—patterns that worked, decisions that were made, context that was missing—and write it back to their knowledge repo as a PR for human review. Each session improves future performance.

Your agent bundles invoke workers through the VW SDK. The SDK manages session lifecycle, executes prompts (single-turn or multi-turn), streams real-time results, and handles file operations in the worker's workspace. Workers run in isolated environments with access to your internal systems.

Invoke a Virtual Worker

Agent bundles invoke workers using the VW SDK. Create a session, execute prompts, and read results—the platform handles provisioning, bootstrapping, and cleanup.

import { VirtualWorker } from '@firebrandanalytics/ff-agent-sdk/virtual-worker';

const vw = new VirtualWorker({ name: 'my-coder' });
const session = await vw.startSession();

try {
  const result = await session.executePrompt({
    prompt: 'Write a function to validate email addresses',
  });
  console.log(result.promptResponse.response);
} finally {
  await session.end();
}

Multi-Turn Session with Streaming

Workers support multi-turn sessions where each prompt builds on the previous work. Stream real-time progress events and output as the worker executes.

const vw = new VirtualWorker({ name: 'my-coder' });
const session = await vw.startSession();

try {
  // Turn 0: Create the module
  await session.executePrompt({
    prompt: 'Create a utils.ts file with string helper functions',
  });

  // Turn 1: Add tests
  const result = await session.executePrompt({
    prompt: 'Write tests for utils.ts using vitest',
  });

  console.log(`Completed ${session.getTurnCount()} turns`);

  // Read generated files from the worker's workspace
  const code = await session.readFile('utils.ts');
  const tests = await session.readFile('utils.test.ts');
} finally {
  await session.end();
}

const session = await vw.startSession();

try {
  const gen = session.prompt({
    prompt: 'Analyze the codebase and create a detailed report',
  });

  let turnResult;
  while (true) {
    const { value, done } = await gen.next();
    if (done) {
      turnResult = value;
      break;
    }

    switch (value.type) {
      case 'VW_STATUS':
        console.log(`[${value.status}] ${value.message}`);
        break;
      case 'VW_STREAM_EVENT':
        if (value.event.type === 'text') {
          process.stdout.write(value.event.data as string);
        }
        break;
    }
  }
} finally {
  await session.end();
}

Worker Configuration

Workers are configured through the FireFoundry Console or Admin API. Each worker definition includes everything the platform needs to provision and run sessions.

Use Cases