Flue Agent Harness Framework

Flue is an open agent framework designed for building autonomous AI agents using a programmable TypeScript harness. It utilizes a React-like hooks API, allowing developers to build agents that are reactive and stateful.

Key capabilities include:

• Agents: Autonomous entities that maintain context across conversations and events.
• Sandboxes: Secure environments for agents to execute code and perform tasks.
• Subagents: Mechanisms for agents to delegate specialized work.
• Skills: Packaged expertise that agents can load on demand.
• Tools: Custom APIs and data queries defined by the developer.
• MCP Servers: Integration with the Model Context Protocol ecosystem.
• Persistent State: Ability to read and write data across an agent's entire conversation.
• Channels: Deployment to platforms like Slack, Teams, Discord, and GitHub.

The @flue/runtime/config module provides programmatic utilities for discovering, loading, and validating Flue configuration.

Important: This module is intended for host-side tooling (e.g., build scripts, CLI tools) that interacts with the filesystem. It must be imported from build or CLI code and must never be imported from agent modules.

The Cloudflare target builds agents to run inside individual Durable Objects. Each agent conversation receives its own persistent state, durable execution, and global addressability.

Key characteristics:

• Build System: Uses Vite with flue() and @cloudflare/vite-plugin in vite.config.ts.
• Storage: Conversation streams, immutable attachments, and submissions are automatically stored in the Durable Object's SQLite storage.
• Restriction: You cannot use a source-root db.ts; Flue manages storage via Durable Objects, and a db.ts file will cause a build error.
• Identity: Agent identity is tied to the exported function name or the agentName static override. Renaming these changes the storage identity.

Flue Blueprints are Markdown-based implementation guides designed specifically for AI coding agents. They are not npm packages or runtime abstractions. When a developer runs flue add <kind> <name> or flue update <kind> <name>, the Flue CLI fetches these guides and provides them to the coding agent, which then performs the actual file edits, dependency installations, and configuration in the user's project.

Blueprints are categorized into four supported kinds:

• sandbox: A sandbox adapter for a remote execution provider.
• channel: Verified provider ingress, a client, and application-owned tools.
• database: A database adapter implementing Flue's PersistenceAdapter.
• tooling: Developer-tool integrations like observability or evaluation.

Flue provides two distinct ways to observe agent activity:

1. Conversation Stream (Product Surface): Used for delivering durable, render-ready messages and settlements to a UI. Consumed over HTTP via the Flue Agent SDK using createFlueClient(...) with observe() or history() methods. This is for the end-user experience.
2. Runtime Event Stream (Operational Surface): Used for telemetry, metering, and error reporting. Consumed in-process via observe() from @flue/runtime. It provides raw activity like model requests, tool executions, and token counts across all agents in the process.

Correlation: You can link the two surfaces using submissionId. A conversation message's submissionId matches the runtime events produced by that specific submission.

The MySQL adapter persists Flue runtime state, including:

• The canonical append-only conversation stream for agent instances.
• Immutable external attachments referenced by conversation records.
• Accepted direct prompts and dispatch(...) submissions (including durable claims and leases).
• Workflow-run records, event streams, and run indexing.

Note: This adapter is intended for runtime state. It should not be used to store application business data, external API side effects, or provider credentials.

Migrations: There is no separate migration command. The adapter's migrate() hook runs automatically at startup to create and verify InnoDB tables idempotently.

Flue guarantees that every admitted submission (via HTTP prompt, dispatch(...), channel delivery, or scheduled trigger) will reach exactly one durable terminal outcome: completed, failed, or aborted.

This outcome is recorded as a submission_settled record in the conversation's canonical stream. The Flue Agent SDK's wait() method and init().read(...) calls resolve or reject based on this record, ensuring consistency even across process crashes or redeploys.

The Cloudflare Shell adapter is not a standard bash-backed sandbox. It provides standard file tools (read, write, edit) but replaces shell commands (bash, grep, glob) with a code tool. This code tool executes JavaScript against the Workspace state.* API within an isolated Worker.

Key Constraints:

• No Shell: harness.sandbox.exec() will throw. Use the code tool for logic.
• No Linux Toolchains: If you need Linux commands, language toolchains, or R2-mounted filesystems, use @cloudflare/sandbox Containers with mountBucket instead.
• Isolation: The code tool runs in an environment with no network access, no DOM, no Node.js APIs (like require, process, or Buffer), and no imports.

A sandbox is an execution environment attached to an agent via the useSandbox() hook. It provides a filesystem and a shell where the agent can read, write, and run commands.

Attaching a sandbox provides:

• File and shell tools: The agent gains read, write, edit, bash, grep, and glob tools.
• Workspace context: The agent's system prompt is automatically populated with the working directory path, a directory listing, and the contents of AGENTS.md (if present).
• Workspace skills: Skill directories located under <cwd>/.agents/skills/ are automatically discovered and offered to the agent.
• Subagent inheritance: Subagents share the same filesystem and tools as their parent agent.
• Application access: Your application code can use harness.sandbox to stage files in and out of the agent's environment without adding them to the conversation history.

A skill is a package of reusable expertise consisting of markdown instructions and optional supporting files (like checklists or templates). Unlike tools which execute code, skills teach an agent a specific procedure.

Skills are progressively disclosed: only the name and description are included in the system prompt to save context. The full instructions and supporting files are only loaded when the model decides to activate the skill via the activate_skill tool.