Frequently Asked Questions About Flue Harness-First AI Agent Framework
21 answers covering everything from basics to advanced usage.
// Basics
What is a harness-first AI agent framework?
A harness-first framework provides the full infrastructure layer — sandboxes, skills, tools, sessions, memory, and system prompt injection — around your LLM from the start. Instead of manually wiring each component as you would in a granular framework, everything is available by default. Flue's harness-first design mirrors how Claude Code wraps a harness around its model, so every agent you create gets production-grade infrastructure in a few lines of TypeScript.
What is Pico and how does Flue relate to it?
Pico is the minimal agent harness core that Flue is built on — the same core underlying Open Claude. Flue wraps a full framework around Pico's agent core, adding skills, tools, sandbox management, deployment targets, and CLI tooling. Think of Pico as the engine and Flue as the complete vehicle. You interact with Flue's API; Pico handles the low-level agent orchestration underneath.
What LLM providers does Flue support?
Flue supports any LLM provider supported by Pico, including Anthropic (Claude). You configure your provider API key during setup and specify the model when defining your agent. Since Pico abstracts the provider layer, switching models typically requires changing only the model name and API key in your agent definition, not rewriting your agent logic or tool integrations.
What is an agent.md file in Flue?
An `agent.md` file placed at the project root provides persistent system context that is injected into the agent's system prompt. It serves as a project-level instruction set that all agents in the project can reference. Use it for shared context like coding standards, domain terminology, or behavioral guidelines. Agent-specific instructions are set separately in the agent definition and append to whatever `agent.md` provides.
What is Valibot and why does Flue use it for tool parameters?
Valibot is a lightweight TypeScript schema validation library. Flue uses it to define and validate tool parameters, ensuring that when an agent invokes a tool, the inputs match the expected types and constraints. This creates tight parameter contracts, preventing runtime errors from malformed inputs. Valibot's small bundle size aligns with Flue's emphasis on minimal overhead, especially when deploying to edge environments like Cloudflare Workers.
// How To
How do I install and set up Flue for the first time?
Install the Flue runtime and Flue CLI via npm. Run `flue init` and select your deployment target — Node (HTTP server via Hono) or Cloudflare (Worker + Durable Object). This generates a `flue.config.ts` configuration file. Set your LLM provider API key as an environment variable. Create your first agent in the `agents/` directory or workflow in `workflows/`, then test with `flue connect` or `flue run`.
How do I add a custom tool to a Flue agent?
Load your backing script (e.g., a Python file), define input parameters using Valibot for validation, and register the tool programmatically on the agent. The tool wraps your script or function with a strict parameter contract. This approach is preferred over using skills when you need type-safe inputs or want to avoid exposing local files to the sandbox. The agent can then invoke the tool during execution.
How do I trigger a Flue workflow via HTTP?
Add the root middleware to your project, then build with `flue build` specifying your target and port. The output `server.mjs` file exposes workflows via HTTP POST. Send a POST request to the workflow endpoint with a JSON payload matching the workflow's typed payload schema. Poll the workflow status via GET, or use WebSockets for streaming results. Deploy `server.mjs` to any Node.js-compatible host.
How do I create a skill.md file for a Flue skill?
Create a directory inside `skills/` at your project root. Add a `skill.md` file that describes what the skill does in natural language — the agent reads this description to understand when and how to invoke the skill. Include any backing scripts (e.g., Python, TypeScript) alongside the skill.md. Register the skill on your agent via the skill input attribute. Keep the description precise so the agent reliably selects it.
// Troubleshooting
Why is my Flue skill failing to find local files?
The default just-bash sandbox has no access to your local file system. If your skill relies on local scripts, either import `local` from `flue-runtime-node` and set the current working directory to the correct skill folder, or wrap the script as a custom tool. A common mistake is importing `local` without setting the working directory — the agent searches for files in the wrong location and fails, wasting tokens and time.
Why does flue build fail with no config file error?
The `flue.config.ts` file is required for the CLI to know how to package your project. If you skipped `flue init` or deleted the config file, the build pipeline breaks. Run `flue init` again, select your deployment target (Node or Cloudflare), and ensure the generated `flue.config.ts` exists at your project root. The config uses Vite under the hood and tells the CLI everything about your project structure.
My Flue agent isn't finding my workflow or agent files — what's wrong?
Flue's CLI resolves paths based on directory conventions: agents must be in `agents/`, workflows in `workflows/`, and skills in `skills/` from the project root. If your files are in the wrong directory, the CLI won't detect them. Check your project structure and ensure each file is in its correct directory. This is a common pitfall when migrating from other frameworks with different conventions.
How do I debug a Flue agent that's using too many tokens?
Check the JSON output from `flue run` or `flue connect`, which includes input/output token counts, cost, and model used. Common causes of excessive token usage: imprecise instructions causing the agent to loop, skills with vague `skill.md` descriptions leading to misselection, or using `local` without setting the correct working directory (the agent repeatedly fails and retries). Tighten instructions, improve skill descriptions, and verify file paths.
// Comparisons
How does Flue compare to building agents with the Vercel AI SDK?
The Vercel AI SDK provides primitives for streaming, tool calling, and model routing but requires you to wire sessions, memory, and sandboxes yourself. Flue wraps all of this into a harness-first framework — sandboxes, skills, tools, and sessions work out of the box. Flue is better when you want a complete agent runtime with minimal configuration; the Vercel AI SDK is better when you need granular control over each streaming and routing step.
Should I use Flue or CrewAI for multi-agent workflows?
CrewAI focuses on multi-agent collaboration with role-based agents orchestrated together. Flue focuses on harness-first single-agent or workflow design with sandboxes, skills, and tools built in. If you need agents that delegate to each other with defined roles, CrewAI is purpose-built for that. If you need individual agents with real tool execution, sandbox isolation, and simple deployment to Node or Cloudflare, Flue is more appropriate.
How does Flue's sandbox compare to running tools in Docker containers?
Flue's default sandbox uses just-bash — an in-memory TypeScript reimplementation of bash — which provides grep, glob, and read capabilities with zero container boot time and near-zero cost. Docker containers offer full OS isolation but add boot latency and per-container cost. Flue lets you run thousands of agents cheaply with just-bash and only opt into real containers (Daytona, Cloudflare sandbox) when you need full OS capabilities.
// Advanced
Can I use Flue with Python instead of TypeScript?
Flue itself is a TypeScript framework — your agent definitions, workflows, and tool registrations are written in TypeScript. However, your tools and skills can invoke Python scripts. You can wrap a Python script as a custom tool with Valibot parameter validation, or include Python scripts in your skill directories. To run Python, either use `local` from `flue-runtime-node` or use a real container sandbox that has Python installed.
How do Flue instance IDs work with Cloudflare Durable Objects?
Every running Flue agent gets a unique instance ID — any string you choose. When deploying to the Cloudflare target, this ID maps directly onto its own Durable Object instance, giving each agent isolated persistent state. This means agent sessions, memory, and context survive restarts. On the Node target, the same ID enables managing multiple concurrent agent sessions in memory. Use stable IDs for persistent agents and unique IDs for ephemeral jobs.
Can I mix agents and workflows in the same Flue project?
Yes. Place agents in the `agents/` directory and workflows in the `workflows/` directory within the same project. Both are compiled and inlined into the same `server.mjs` output when you build. Agents are accessed via `flue connect` or WebSockets for interactive sessions; workflows are triggered via `flue run` or HTTP POST. They can share the same skills directory and project-level `agent.md` system context.
How do I stream Flue workflow results in real time?
Instead of using HTTP POST and polling with GET, use WebSocket connections to stream workflow results. Add the root middleware to your project, build with `flue build`, and connect to the WebSocket endpoint exposed by `server.mjs`. The WebSocket connection delivers incremental output as the workflow executes, making it ideal for UIs or dashboards that need to show progress in real time.
When should I use a real container sandbox instead of just-bash in Flue?
Use a real container sandbox only when your agent needs full OS capabilities — installing packages, running compiled binaries, executing system-level commands, or requiring network access from within the sandbox. For most use cases involving file reading, text processing, and running simple scripts, the in-memory just-bash sandbox is sufficient and dramatically cheaper. Reaching for a real container by default adds unnecessary boot latency and cost.