Flue

Overview

Flue is "The sandbox agent framework" for building autonomous agents via TypeScript. Developed by the Astro team, Flue enables secure, context-aware AI workflows with tools, skills, and sandboxes. It's designed for developers who want to build production-grade autonomous agents with strong type safety and modern web development practices.

Flue provides a complete platform for agent development, including durable execution that recovers progress after failures, sub-agent delegation for task specialization, and integration with the Model Context Protocol (MCP) for connecting to external services.

The framework has gained attention in the TypeScript/JavaScript ecosystem with over 6,700 GitHub stars, offering an alternative to Python-dominated agent frameworks.

Features

• TypeScript-First: Full type safety for agent definitions, tools, and workflows
• Sandbox Execution: Secure environments for file and tool access
• Durable Execution: Automatic recovery of progress after failures or restarts
• Sub-Agent Delegation: Delegate tasks to specialized roles with isolated contexts
• Tools and Skills: Typed actions and reusable expertise modules
• MCP Integration: Connect to external services via Model Context Protocol
• Observability: Built-in telemetry via OpenTelemetry, Sentry, and other tools
• Channel Integration: Connect to Slack, GitHub, and other platforms
• Workflows: Structured automations guided by code
• Context Management: Maintain context across sessions for goal-driven autonomy

Installation

Prerequisites

• Node.js 18+
• npm, yarn, or pnpm

Quick Install

# Install the Flue runtime
npm install @flue/runtime

# Or with yarn
yarn add @flue/runtime

# Or with pnpm
pnpm add @flue/runtime

Project Setup

# Create a new Flue project
npm create flue@latest my-agent
cd my-agent
npm install
npm run dev

Quick Start

Basic Agent Definition

import { defineAgent, local } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  tools: [githubTools, filesystemTools],
  skills: [triage, verify],
  sandbox: local(),
  instructions: `
    You are a code review agent. Your job is to:
    1. Review pull requests for bugs and security issues
    2. Suggest improvements with specific code examples
    3. Verify that fixes address the reported issues
  `,
}));

Defining Tools

import { defineTool } from '@flue/runtime';

export const searchCode = defineTool({
  name: 'search_code',
  description: 'Search for code patterns in the repository',
  parameters: {
    query: { type: 'string', description: 'Search query' },
    path: { type: 'string', description: 'Directory to search in' },
  },
  execute: async ({ query, path }) => {
    // Tool implementation
    return await searchRepository(query, path);
  },
});

Defining Skills

import { defineSkill } from '@flue/runtime';

export const codeReview = defineSkill({
  name: 'code_review',
  description: 'Review code for quality and security',
  tools: [searchCode, analyzeSecurity],
  instructions: `
    Review all changes thoroughly. Check for:
    - Security vulnerabilities
    - Performance issues
    - Code style violations
    - Missing error handling
  `,
});

Workflow Definition

import { defineWorkflow, sequential } from '@flue/runtime';

export default defineWorkflow({
  name: 'pr-review-workflow',
  steps: sequential([
    {
      agent: 'reviewer',
      task: 'Review the pull request',
      tools: [githubTools, codeAnalysisTools],
    },
    {
      agent: 'tester',
      task: 'Run tests and verify changes',
      tools: [testingTools, ciTools],
    },
    {
      agent: 'approver',
      task: 'Make final approval decision',
      tools: [githubTools],
    },
  ]),
});

Core Concepts

Agents

Agents in Flue maintain context across sessions, enabling goal-driven autonomy. Each agent has:

• A model configuration
• A set of tools and skills
• A sandbox environment
• Instructions defining behavior

Workflows

Workflows are structured automations that coordinate multiple agents. They define:

• The sequence of steps
• Which agent handles each step
• How data flows between steps
• Error handling and retry logic

Sandboxes

Sandboxes provide secure execution environments for agent tools. Flue supports:

• Local sandbox: Runs on the local filesystem with restricted access
• Container sandbox: Isolated Docker containers for full isolation
• Remote sandbox: Cloud-based execution environments

Durable Execution

Flue automatically saves execution state, allowing agents to recover from:

• Process crashes
• Network interruptions
• Resource limits
• Manual interruptions

When execution resumes, the agent picks up where it left off with full context.

Advanced Features

Sub-Agent Delegation

Agents can delegate tasks to specialized sub-agents:

const mainAgent = defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  instructions: `
    You coordinate a team of specialized agents.
    Delegate tasks based on expertise.
  `,
  subAgents: [
    codeReviewer,
    tester,
    documenter,
  ],
}));

MCP Server Integration

Flue integrates with MCP servers for external service access:

import { mcpServer } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  tools: [
    mcpServer('github', {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-github'],
      env: { GITHUB_TOKEN: process.env.GH_TOKEN },
    }),
    mcpServer('filesystem', {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', './'],
    }),
  ],
}));

Observability

Flue provides built-in observability:

import { withTelemetry } from '@flue/runtime';

export default withTelemetry(defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  // ...
})), {
  provider: 'opentelemetry',
  endpoint: process.env.OTEL_ENDPOINT,
  serviceName: 'my-agent',
});

Channel Integration

Connect agents to communication channels:

import { slackChannel, githubChannel } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  channels: [
    slackChannel({
      token: process.env.SLACK_TOKEN,
      channels: ['#dev', '#alerts'],
    }),
    githubChannel({
      token: process.env.GH_TOKEN,
      repos: ['myorg/myrepo'],
    }),
  ],
}));

Examples

Code Review Bot

import { defineAgent, githubTools } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  tools: githubTools,
  skills: [codeReviewSkill],
  sandbox: local(),
  instructions: `
    Monitor pull requests and provide detailed reviews.
    Focus on security, performance, and maintainability.
  `,
  channels: [githubChannel({ token: process.env.GH_TOKEN })],
}));

Research Agent

import { defineAgent, webSearch } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  tools: [webSearch, browserTools],
  skills: [researchSkill, reportGeneration],
  sandbox: container(),
  instructions: `
    Research topics thoroughly and generate comprehensive reports.
    Verify information from multiple sources.
  `,
}));

CI/CD Assistant

import { defineAgent, ciTools } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  tools: ciTools,
  skills: [debugSkill, fixSkill],
  sandbox: container(),
  instructions: `
    Monitor CI/CD pipelines and automatically fix common issues.
    Escalate complex problems to human developers.
  `,
  channels: [slackChannel({ token: process.env.SLACK_TOKEN })],
}));

Pros

• ✅ TypeScript-first with full type safety
• ✅ Durable execution with automatic recovery
• ✅ Strong sandbox security model
• ✅ Excellent observability support
• ✅ MCP integration for external services
• ✅ Active development by Astro team
• ✅ Modern web development practices
• ✅ Great for Node.js/JavaScript ecosystems

Cons

• ❌ Newer framework with smaller community than Python alternatives
• ❌ Limited pre-built skills compared to CrewAI/LangChain
• ❌ Primarily TypeScript-focused (limited Python support)
• ❌ Documentation still evolving
• ❌ Fewer learning resources and tutorials
• ❌ Model provider support may be more limited

When to Use

Flue is ideal for:

• TypeScript/JavaScript projects needing agent capabilities
• Web applications that want to integrate AI agents
• Teams familiar with Node.js ecosystem
• Applications requiring durable execution and recovery
• Projects needing strong type safety
• CI/CD and DevOps automation in JavaScript environments

Consider Python frameworks (CrewAI, LangGraph, DeerFlow) for:

• Data science and ML workflows
• Projects with existing Python codebases
• Access to broader AI/ML ecosystem
• More mature agent frameworks with larger communities

Resources

• Official Website
• GitHub Repository
• Documentation
• Examples
• Contributing Guide