Setting Up Your Production-Ready Flue Development Environment

Building production-ready AI agents requires a solid foundation, starting with a properly configured development environment. In this chapter, we’ll guide you through setting up everything you need to start crafting intelligent agents using the Flue Framework. We’ll move from understanding Flue’s unique architecture to getting your first project initialized and ready for action.

Why does a robust setup matter? A well-configured environment prevents countless headaches down the line, especially when dealing with TypeScript’s strictness and the intricacies of agent frameworks. By the end of this chapter, you’ll have a clean, ready-to-code workspace, prepared for the practical agent-building ahead.

Before we dive in, ensure you’re comfortable with basic command-line operations and have a text editor or IDE (like VS Code) at hand. Familiarity with Node.js and TypeScript fundamentals will also be beneficial, as Flue heavily leverages these technologies.

Understanding the Flue Agent Harness Architecture

When we talk about building AI agents, it’s easy to conflate “using an LLM” with “building an agent.” Flue bridges this gap by providing an agent harness architecture. This is a critical distinction from mere Large Language Model (LLM) SDK wrappers.

What is an Agent Harness?

An agent harness, like Flue, is a structured environment designed to host, manage, and execute AI agents. It provides the surrounding infrastructure that allows an agent to go beyond just generating text, enabling it to act and interact.

Here’s why an agent harness is essential:

Sandboxed Execution: Agents, especially “coding agents,” often need to run shell commands, interact with a filesystem, or execute arbitrary code. A harness provides a secure, isolated environment (a sandbox) for these operations. This prevents an agent’s actions from affecting the host system, crucial for security and stability in production.
Stateful Sessions: Unlike stateless API calls, real-world agents need memory. A harness maintains context across multiple interactions, enabling complex, multi-turn conversations or long-running tasks that require remembering previous steps or information.
Tool and Skill Integration: Agents gain capabilities beyond pure language generation by calling external tools (e.g., APIs, databases, custom functions) and leveraging pre-defined “skills” (like Markdown rendering, specific data processing, or interacting with a knowledge base). The harness manages these integrations.
Standardized Interfaces: Flue allows agents to be exposed over standard protocols like HTTP or WebSockets, making them easily consumable by other applications and services in a distributed system.

Flue vs. LLM SDK Wrappers

Let’s clarify the difference with an analogy:

LLM SDK Wrapper: Imagine this as a high-quality phone that lets you call an expert. You can ask questions, and the expert (LLM) provides answers. It handles the connection and communication, but the expert’s knowledge is limited to what they know, and they can’t do anything beyond talking.
Flue Agent Harness: This is like building a fully-equipped robot that uses that phone to call the expert. The robot has a body (the harness), hands (tools/skills), memory (state), and a controlled workshop (sandbox) where it can follow instructions from the expert. The robot can not only get answers but also perform actions based on those answers, like writing code, searching the web, or managing files.

📌 Key Idea: Flue is not just a wrapper for an LLM API; it’s an operational framework that provides the “body” and “environment” for intelligent, stateful, and tool-augmented agents to perform complex tasks in a controlled manner.

This distinction is vital for production-minded engineers. A basic LLM call can answer a question, but a Flue agent can act on that answer, persist its findings, and even self-correct within a controlled environment, making it suitable for real-world applications.

Let’s visualize this agent harness architecture:

flowchart TD User_App[User Application or Service] -->|Agent Request| Agent_Harness[Flue Agent Harness] subgraph Agent_Harness_Internal["Flue Agent Harness"] Agent_Harness --> Session_Manager[Session Manager] Session_Manager --> State_Store[Persistent State Store] Agent_Harness --> Sandbox_Exec[Sandboxed Execution] Sandbox_Exec --> LLM_Provider[LLM Provider API] Sandbox_Exec --> Tools_Services[External Tools Services] LLM_Provider -->|LLM Response| Sandbox_Exec Tools_Services -->|Tool Results| Sandbox_Exec State_Store -->|Load Save State| Session_Manager end Sandbox_Exec -->|Agent Output| Agent_Harness Agent_Harness -->|Agent Response| User_App

⚡ Real-world insight: This sandboxed execution and state management are what enable Flue to power complex coding agents that can, for example, write and execute code snippets, debug issues, or manage project files within their isolated environment. This capability is crucial for automating developer workflows or building sophisticated AI assistants.

Setting Up Your Development Environment

To start building with Flue, you’ll need Node.js and npm (which comes bundled with Node.js), along with TypeScript for type-safe development.

Step 1: Install Node.js and npm

Flue is built on Node.js, so you’ll need a recent stable version. As of June 2026, Node.js v22.5.0 (or a similar LTS release from the 22.x or 24.x series) is an excellent choice for stability and modern features.

Check your current Node.js version: Open your terminal or command prompt and run:
```
node -v
npm -v
```
If you see versions older than 20.x, or if they’re not installed, proceed to the next step.
Install Node.js: The recommended way to install Node.js is using a version manager like nvm (Node Version Manager). This allows you to easily switch between different Node.js versions for various projects, which is a common practice in production environments.
- Install nvm (if you don’t have it): Follow the installation instructions on the official nvm GitHub page: https://github.com/nvm-sh/nvm
- Install a specific Node.js version using nvm: Once nvm is installed, use these commands:
```
nvm install 22.5.0
nvm use 22.5.0
nvm alias default 22.5.0 # Set this as the default for new shells
```
  These commands install Node.js v22.5.0 and set it as the active version for your current shell and future shells.
- Verify installation: Run the version check commands again:
```
node -v
npm -v
```
  You should now see v22.5.0 (or your chosen version) and a compatible npm version (usually 9.x or 10.x).

Step 2: Initialize Your Flue Project

Now that Node.js is ready, let’s create a new project and install Flue.

Create a new project directory: Open your terminal and create a new folder for your project. Then navigate into it.
```
mkdir my-first-flue-agent
cd my-first-flue-agent
```
Initialize a Node.js project: This command creates a package.json file, which manages your project’s dependencies and scripts.
```
npm init -y
```
The -y flag answers “yes” to all prompts, creating a default package.json.
Install Flue and TypeScript: We’ll install Flue, TypeScript, and @types/node for Node.js type definitions.
```
npm install flue typescript @types/node --save-dev
```
Here’s what each package does:
- flue: The core Flue framework.
- typescript: The TypeScript compiler itself.
- @types/node: Provides type definitions for Node.js APIs, essential for TypeScript to understand global Node.js objects and functions.

Configure TypeScript: Create a tsconfig.json file in your project root. This file tells the TypeScript compiler how to compile your code, defining target versions, module resolution, and strictness rules.

npx tsc --init --rootDir src --outDir dist --esModuleInterop --resolveJsonModule --lib es2022 --module commonjs --target es2022 --strict

This command generates a tsconfig.json with sensible defaults for a Node.js project. Let’s briefly look at some key options:

rootDir src: Specifies that your source code will reside in the src/ directory.
outDir dist: Dictates that compiled JavaScript will be output to the dist/ directory.
esModuleInterop: Allows you to use import x from 'y' syntax even for CommonJS modules, improving compatibility.
resolveJsonModule: Enables importing .json files directly into your TypeScript code.
lib es2022, module commonjs, target es2022: Configures the project to use modern JavaScript features (ES2022) and CommonJS module system, which is standard for Node.js.
strict: Enables all strict type-checking options, a crucial best practice for writing robust and maintainable code in TypeScript.

Open the generated tsconfig.json and ensure it looks similar to this (many comments will be present, but these are the key uncommented lines):

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
    "module": "commonjs",                                /* Specify what module code is generated. */
    "rootDir": "./src",                                  /* Specify the root folder within your source files. */
    "outDir": "./dist",                                  /* Specify an output folder for all emitted files. */
    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
    "strict": true,                                      /* Enable all strict type-checking options. */
    "skipLibCheck": true,                                /* Skip type checking all .d.ts files. */
    "resolveJsonModule": true,                           /* Enable importing .json files. */
    "lib": ["es2022"]                                    /* Specify a list of library files to be included in the compilation. */
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

Create your first source file: Create a src directory and an index.ts file inside it. This will be your entry point.
```
mkdir src
touch src/index.ts
```
Open src/index.ts in your editor and add a simple console.log to confirm everything is working.
```
// src/index.ts
console.log("Hello, Flue Agent!");
```
Add build and start scripts: Open your package.json file and add build and start scripts to compile and run your TypeScript code. This automates the development workflow.
```
// package.json
{
  "name": "my-first-flue-agent",
  "version": "1.0.0",
  "description": "A basic Flue agent project setup.",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": ["flue", "agent", "typescript", "ai"],
  "author": "Your Name",
  "license": "ISC",
  "devDependencies": {
    "@types/node": "^20.14.2",
    "flue": "latest",
    "typescript": "^5.4.5"
  }
}
```
- "flue": "latest": We specify latest for Flue’s version, reflecting its current known state as of June 2026 without an explicit stable release number in the provided context. When a stable version is released, you would typically pin it (e.g., "flue": "1.0.0").
- "@types/node": "^20.14.2" and "typescript": "^5.4.5": These are the latest stable versions as of June 2026, ensuring compatibility with our chosen Node.js version.
Test your setup: Compile and run your simple script from the project root.
```
npm run build
npm start
```
You should see the output:
```
Hello, Flue Agent!
```
If you see this, congratulations! Your Flue development environment is correctly set up and ready for agent development.

Mini-Challenge: Prepare for Your First Agent

Now that your environment is ready, let’s take a tiny but crucial step towards building your first Flue agent.

Challenge: Inside your src directory, create a new file named myAgent.ts. In this file, import the Agent class from flue and declare a simple (empty for now) class that extends Agent. This will be the foundational skeleton for our first intelligent agent in the next chapter.

Hint: Remember that Flue is a TypeScript-first framework. You’ll need an import statement to bring in the Agent class and a class declaration using the extends keyword.

Stuck? Click for a hint!

Your `myAgent.ts` file might start something like this: ```typescript // src/myAgent.ts import { Agent } from 'flue';

class MyFirstAgent extends Agent { // Agent logic will go here }

// You might export it later to use it in other parts of your application export default MyFirstAgent;

</details>

**What to observe/learn:**
This challenge reinforces the TypeScript-first approach of Flue and introduces you to the basic structural pattern of a Flue agent class. It's a small step, but it confirms your understanding of module imports and class extensions within your new Flue project, which are fundamental building blocks.

## Common Pitfalls & Troubleshooting

Setting up development environments can sometimes lead to unexpected issues. Here are a few common mistakes and how to address them, ensuring you can quickly get back on track.

*   **Node.js Version Mismatch:**
    *   **Symptom:** Errors about unsupported syntax, missing `npm` commands, or features not found.
    *   **Solution:** Your Node.js version might be too old or not the one you intended to use. Use `nvm use <version>` to switch to the correct version, or `nvm install <version>` to get a newer one. Always verify your active version with `node -v` and `npm -v`.
*   **TypeScript Compilation Errors:**
    *   **Symptom:** `Cannot find module 'flue'` or `Cannot find name 'Agent'`.
    *   **Solution:** This usually means `flue` wasn't installed correctly, or your `tsconfig.json` isn't configured to include `node_modules` or your `src` directory. Double-check that `npm install flue` ran without errors and review your `tsconfig.json`'s `include` and `exclude` paths.
    *   **Symptom:** Type errors related to `console.log` or other Node.js globals (e.g., `Error: Cannot find name 'console'`).
    *   **Solution:** Ensure `@types/node` is installed (`npm install @types/node --save-dev`) and your `tsconfig.json` includes `lib: ["es2022"]` (or a similar modern `lib` array) which provides global type definitions for Node.js environments.
*   **`npm run build` fails or `npm start` can't find `dist/index.js`:**
    *   **Symptom:** The build script fails, or the `start` script reports that `dist/index.js` does not exist.
    *   **Solution:**
        1.  Verify your `package.json` scripts: `"build": "tsc"` and `"start": "node dist/index.js"`.
        2.  Ensure your `tsconfig.json`'s `outDir` is set to `./dist` and `rootDir` is set to `./src`.
        3.  Confirm your entry source file is actually located at `src/index.ts`.
*   **`npx` command not found:**
    *   **Symptom:** The terminal reports `npx: command not found` when trying to run `npx tsc --init`.
    *   **Solution:** `npx` comes bundled with npm `v5.2.0` and higher. If you get this error, you likely have an old npm version. Update npm globally by running `npm install -g npm@latest` or update your Node.js installation.

🧠 **Important:** Always read the error messages carefully. They often point directly to the problem, whether it's a missing file, an incorrect configuration, or a syntax error. Don't be afraid to search online for specific error messages, as they are often common and have well-documented solutions.

## Summary

In this chapter, you've successfully laid the groundwork for building sophisticated AI agents with the Flue Framework. This foundational setup is critical for developing robust and production-ready applications.

Here are the key takeaways:

*   **Flue is an Agent Harness, Not Just an LLM Wrapper:** It provides a comprehensive environment for sandboxed execution, state management, and tool integration, empowering agents to act intelligently and persistently.
*   **Node.js and TypeScript are Core:** Your development environment relies on a modern Node.js installation (e.g., v22.5.0 as of June 2026) and a well-configured TypeScript setup (e.g., v5.4.5) for type safety and maintainability.
*   **Project Setup is Incremental:** You learned to initialize a Node.js project, install Flue and its dependencies, configure TypeScript, and create basic `build` and `start` scripts.
*   **A Solid Foundation:** Your environment is now meticulously prepared for the exciting task of defining and implementing your first intelligent agent, ensuring a smooth development experience.

In the next chapter, we'll dive into the core concepts of creating a Flue agent, defining its capabilities, and making it respond to prompts and interact with its environment. Get ready to bring your agent to life!

## References

*   [Node.js Official Website](https://nodejs.org/en/)
*   [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
*   [nvm (Node Version Manager) GitHub Repository](https://github.com/nvm-sh/nvm)
*   [Flue — The Agent Harness Framework Official Website](https://flueframework.com)
*   [withastro/flue GitHub Repository](https://github.com/withastro/flue)

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.