Flue: Guia Definitivo — O Framework de Agentes do Time Astro

TL;DR: Flue é o framework TypeScript open-source (Apache 2.0) do time Astro para construir agentes autônomos — “like Claude Code, but 100% headless and programmable”. Roda sobre o Pi (o mesmo harness do OpenClaw), usa Durable Streams para sobreviver a crashes, importa skills como arquivos markdown via with { type: 'skill' }, e faz deploy em Node, Cloudflare Workers, GitHub Actions, GitLab CI, Docker, Railway ou Fly. A versão 1.0 Beta saiu em 16 de junho de 2026. Se você escreve TypeScript e precisa de agentes que rodam em background sem depender de um humano colado no terminal, este é provavelmente o framework mais bem desenhado do momento.

O que é o Flue — e por que o time do Astro decidiu criar um framework de agentes

Você conhece o Astro — o meta-framework web que virou referência em performance e developer experience. (Este blog, aliás, é construído com Astro.) Pois o mesmo time que te deu content collections, islands architecture e zero-JS-by-default agora olhou pro problema de agentes IA e disse: “isso precisa da mesma filosofia de DX que trouxemos pra web.”

O resultado é o Flue: um framework TypeScript para construir agentes autônomos que funciona como harness programável. A frase que melhor captura a essência:

“Flue is to agents what Astro is to websites.” — Flavio Copes

Isso não é hipérbole. A filosofia é idêntica: convenção sobre configuração, filesystem-first, write once deploy anywhere, e uma obsessão quase maníaca por developer experience sem sacrificar poder.

A genealogia técnica

Flue não surgiu do nada. Ele empilha sobre o Pi — um agent harness open-source que é o motor por trás do OpenClaw. Se você leu nosso guia sobre Pi, já conhece a arquitetura: um loop agêntico que chama tools, lê resultados, gerencia contexto e continua até a tarefa terminar.

A relação entre as camadas ficou cristalina no post técnico da Cloudflare:

• Framework (Flue) → estrutura de projeto, convenções, integrações, CLI, DX
• Harness (Pi) → o loop agêntico que chama tools e gerencia contexto
• Runtime/Platform (Cloudflare Agents SDK, Node, etc.) → compute, state, storage

Isso mapeia perfeitamente no conceito de harness e loop que já discutimos aqui no blog. Pi é o harness. O modelo + skills + tools formam o loop. Flue é a casca de DX que torna tudo produtivo.

Por que existe — a origem prática

O BetterStack conta a história de origem: Flue foi construído originalmente para automatizar workflows de IA dentro dos próprios repositórios do Astro no GitHub. Não nasceu como produto — nasceu como necessidade interna. Issue triage, code review automatizado, PR labeling, release notes. O time do Astro precisou de agentes que rodavam em background, sem TUI, sem GUI, disparados por webhooks.

Quando perceberam que estavam resolvendo um problema universal, abriram o código.

Tutorial: Do Zero ao Primeiro Agente

Chega de contexto — vamos colocar a mão na massa.

1. Instalação

mkdir meu-agente && cd meu-agente
npm install @flue/runtime
npm install --save-dev @flue/cli

Crie um .env com sua API key:

ANTHROPIC_API_KEY="sk-ant-..."

Inicialize o projeto:

npx flue init --target node

Isso gera um flue.config.ts:

import { defineConfig } from '@flue/cli/config';

export default defineConfig({
  target: 'node',
});

O target pode ser 'node' (servidor Hono) ou 'cloudflare' (Worker com Durable Objects). Essa decisão é sobre onde roda — não muda como você escreve o agente.

2. Definindo o agente

Flue segue uma convenção de diretório: agentes vivem em agents/, workflows em workflows/. O nome do arquivo vira o ID do agente.

mkdir agents

// agents/triage.ts
import { defineAgent } from '@flue/runtime';
import { local } from '@flue/runtime/node';
import triage from '../skills/triage/SKILL.md' with { type: 'skill' };
import { replyToIssue } from '../tools/github.ts';

export default defineAgent(() => ({
  model:   'anthropic/claude-sonnet-4-6',
  tools:   [replyToIssue],
  skills:  [triage],
  sandbox: local(),
  instructions: `Triage a bug report end-to-end:
    reproduce the bug, diagnose the root cause,
    verify whether the behavior is intentional,
    and attempt a fix.`,
}));

Olha a elegância disso. Em menos de 15 linhas você declarou:

• Qual modelo usar (qualquer provider, via formato provider/model)
• Quais tools o agente pode chamar (tipadas em TypeScript)
• Quais skills carregam expertise reutilizável (markdown!)
• Qual sandbox dá ambiente de execução
• Quais instruções guiam o comportamento

Não tem loop pra escrever. Não tem graph pra desenhar. Não tem YAML pra configurar. É TypeScript declarativo — o tipo de código que se auto-documenta.

3. Skills como markdown — e por que isso é revolucionário

Aqui a coisa fica pessoal. Este blog ensina há meses que skills markdown são o formato certo para instruções de agentes. Flue validou essa tese ao nível de framework:

import triage from '../skills/triage/SKILL.md' with { type: 'skill' };

O import assertion with { type: 'skill' } diz pro bundler (Vite) que aquele markdown deve ser parseado como skill — com seções de instruções, exemplos, e troubleshooting que viram contexto estruturado pro modelo.

Uma skill é um arquivo SKILL.md que pode conter:

• Instruções detalhadas sobre quando e como agir
• Exemplos de entrada/saída
• Gotchas e lições aprendidas
• Comandos bash que o agente pode executar

Exatamente o padrão que documentamos em ferramentas, tools e MCP servers — e que usamos na prática com as 30+ skills deste próprio homelab.

4. Tools tipadas

// tools/github.ts
import { defineTool } from '@flue/runtime';
import { z } from 'zod';

export const replyToIssue = defineTool({
  name: 'reply_to_issue',
  description: 'Post a comment on a GitHub issue',
  parameters: z.object({
    issueNumber: z.number(),
    body: z.string(),
  }),
  execute: async ({ issueNumber, body }) => {
    const res = await fetch(
      `https://api.github.com/repos/owner/repo/issues/${issueNumber}/comments`,
      {
        method: 'POST',
        headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` },
        body: JSON.stringify({ body }),
      }
    );
    return { success: res.ok };
  },
});

Zod pra validação de parâmetros, TypeScript pra tipagem end-to-end. O modelo vê o schema, a descrição, e sabe exatamente como chamar. Sem surpresas runtime.

5. Rodando

Interativo (para debug):

npx flue connect triage local-session

Como servidor HTTP:

npx flue build --target node
PORT=8080 node dist/server.mjs

Trigger via API:

curl -X POST http://localhost:8080/agents/triage \
  -H "Content-Type: application/json" \
  -d '{"message": "Bug: login page returns 500 on Safari"}'

O servidor responde com um runId e você pode poll pelo resultado ou receber via webhook.

Deep Dive: As 7 Peças que Fazem o Flue Diferente

Durable Streams — Agentes que sobrevivem a crashes

Esse é o killer feature técnico. Todo evento na execução de um agente — cada prompt, cada resposta de tool, cada decisão do modelo — é escrito num append-only log chamado Durable Stream.

Se o processo morre (OOM kill, deploy, crash de infra), outro processo pega o log e continua do exato passo onde parou. Sem perder contexto. Sem refazer trabalho. Sem desperdiçar tokens.

Na Cloudflare, isso usa runFiber() e stash() do Agents SDK:

await this.runFiber("triage-task", async (ctx) => {
  const diagnosis = await reproduzirBug();
  ctx.stash({ diagnosis }); // checkpoint

  const fix = await tentarCorrigir(diagnosis);
  this.setState({ ...this.state, result: fix });
});

Se o processo morre após o stash(), o recovery começa com diagnosis já disponível. Sem refazer a reprodução do bug.

Isso resolve um problema real que todo mundo que já deployou agentes em produção conhece: aquele run de 3 minutos que morre no minuto 2:45 e você perde tudo.

Sandboxes — Do in-memory ao container full

Flue oferece uma hierarquia progressiva de sandboxes:

O design é inteligente: o default é o mais barato possível. Você escala isolamento conforme a necessidade. A maioria dos agentes nunca precisa de um container full — e o Flue não te força a pagar por um.

Subagents — Delegação com isolamento de contexto

import { defineAgent } from '@flue/runtime';
import reviewer from './reviewer.ts';
import fixer from './fixer.ts';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  subagents: [reviewer, fixer],
  instructions: `You are a tech lead. Delegate code review to the reviewer
    and bug fixes to the fixer. Synthesize their outputs.`,
}));

Subagentes rodam com contexto limpo — não poluem a janela do agente pai. Cada um pode ter seu próprio modelo, skills, tools e sandbox. O agente principal orquestra, mas não microgerencia.

Isso é diferente de handoffs (que transferem controle) — aqui o agente principal mantém supervisão e pode pedir revisões ou combinar outputs.

MCP Servers — Plug and play

import { defineAgent } from '@flue/runtime';
import { mcp } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'openai/gpt-4o',
  tools: [
    mcp('github', { url: 'http://localhost:3001/sse' }),
    mcp('filesystem', { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'] }),
  ],
}));

Qualquer MCP server vira tool. stdio ou SSE. Sem adapter, sem wrapper. Se você já tem um ecossistema de MCP servers configurados, o Flue consome todos.

Channels — De Slack a WhatsApp

Channels são como o Flue recebe eventos do mundo externo:

npx flue add channel slack

Isso gera um blueprint markdown que configura verificação de evento, dispatch e roteamento. Channels disponíveis:

• Slack — slash commands, mentions, thread replies
• Discord — bot events
• GitHub — issues, PRs, comments, webhooks
• Microsoft Teams — mensagens e cards
• WhatsApp — via Twilio/Meta API
• Telegram — bot API
• Linear — issues e project updates

Cada channel faz a verificação de assinatura (HMAC, etc.) automaticamente. Você não precisa parsear payloads de webhook na mão.

Observabilidade — Não é afterthought

// flue.config.ts
import { defineConfig } from '@flue/cli/config';
import { opentelemetry } from '@flue/opentelemetry';

export default defineConfig({
  target: 'node',
  observers: [
    opentelemetry({ endpoint: 'http://localhost:4318' }),
  ],
});

Integrações de observabilidade disponíveis:

• OpenTelemetry → qualquer backend (Jaeger, Grafana Tempo, Datadog)
• Braintrust → eval, scoring, datasets
• Sentry → error tracking com contexto de agente

Cada tool call, cada decisão do modelo, cada subagent spawn vira um span. Você rastreia a execução inteira num trace distribuído.

Workflows — Automação finita

Quando você não precisa de um agente autônomo que decide o que fazer, mas sim de um pipeline estruturado com input → processamento → output:

// workflows/yt-titles.ts
import { createAgent, type FlueContext } from '@flue/runtime';
import { readFile } from 'node:fs/promises';
import titleScore from '../skills/title-score/SKILL.md' with { type: 'skill' };

const agent = createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  instructions: 'Generate 10 YouTube titles and rank them using the title-score skill.',
  skills: [titleScore],
}));

export async function run(init: any, payload: FlueContext<{ path: string }>) {
  const harness = await init(agent);
  const session = await harness.session();
  const script = await readFile(payload.path, 'utf8');
  const response = await session.prompt(script);
  return { summary: response.text };
}

Workflows são finitos — input entra, resultado sai. Perfeitos pra cron jobs, CI/CD steps, e processamento batch.

Flue vs Eve (Vercel) — O Comparativo que Importa

Eve e Flue chegaram na mesma semana de junho de 2026. Ambos TypeScript, ambos declarativos, ambos com durable execution e skills markdown. A escolha entre eles se resume a uma pergunta:

Você quer que a plataforma resolva infra pra você, ou quer controle total de onde roda?

A firecrawl.dev resume bem: “Both define an agent declaratively with Markdown instructions, TypeScript tools, durable execution, sandboxes, and channels. They are two of the cleanest ways to build AI agents available today.”

A decisão não é sobre features — é sobre filosofia de deploy. Se você já vive no ecossistema Vercel, Eve reduz fricção. Se precisa de runtime-agnostic com zero lock-in, Flue é a resposta.

Spider Chart

Avaliação em 8 eixos (0–100):

                    Facilidade de Uso
                         85
                          │
        Documentação      │      Ecosystem/Comunidade
              70 ─────────┼───────── 60
                         ╱│╲
      Durable/         ╱  │  ╲      Flexibilidade de
      Resiliência 95 ─╱───│───╲── 90  Deploy
                      ╱   │   ╲
        Observa-     ╱    │    ╲   Multi-Provider
        bilidade 80 ╱─────│─────╲─── 95
                   ╱      │      ╲
                  ╱       │       ╲
         Multi-Agent      │     Maturidade
              80 ─────────┼───────── 55

Prós e Contras

O que brilha

• Zero lock-in real — Não é marketing. O mesmo agente roda em Node, Cloudflare, GitHub Actions sem mudar uma linha de código do agente. Só muda o target no config.

• Skills como markdown são brilhantes — O import assertion with { type: 'skill' } é a melhor implementação de skills-as-code que vi em qualquer framework. Versionáveis, legíveis, portáveis.

• Durable Streams resolvem um problema real — Agentes em produção morrem. Durable execution com append-only log e recovery automático é a diferença entre “demo legal” e “software que roda em prod”.

• Sandboxes progressivas — O default barato (just-bash in-memory) com opt-in pra isolamento pesado é design inteligente. Você não paga por container se não precisa.

• DNA de framework web — O time que fez Astro sabe o que é boa DX. Vite pra build, convenção de diretório, hot reload em dev, CLI polida. Coisas que outros frameworks de agentes ainda não resolveram.

• Headless por design — Sem TUI, sem GUI, sem terminal interativo. Agentes rodam em background, disparados por events. Isso é o que produção precisa.

• @flue/react para quando precisa de UI — Opt-in. Streams estado do agente, execução de tools e mensagens direto pra React. O melhor dos dois mundos.

Onde dói

• Beta recente — 1.0 Beta de junho/2026. Breaking changes vão acontecer. A API não é stable ainda. Se você precisa de estabilidade comprovada, espere.

• Comunidade nascente — Sem a massa crítica de StackOverflow answers, posts de blog, e exemplos que LangChain ou CrewAI têm. Quando você travar, a comunidade pode não ter a resposta.

• Complexidade quando escala — O theroadtoenterprise acerta: “worth its complexity once you keep rebuilding.” Se seu agente é simples (um modelo, uma skill, nenhuma durabilidade), Flue é overhead.

• TypeScript-only — Se seu time é Python, não tem opção. Frameworks como Pydantic AI, CrewAI ou LangGraph servem melhor. (Embora Pi, o harness, seja agnóstico.)

• Documentação em construção — Docs existem mas não estão no nível Astro Docs (que é referência da indústria). Vai melhorar — mas hoje tem gaps.

• Observability não é zero-config — Diferente do OpenAI Agents SDK onde tracing é automático e gratuito, no Flue você precisa configurar o observer. Não é difícil, mas é um passo extra.

Quando usar o Flue

✅ Agentes headless em produção — Se seus agentes rodam em background (CI/CD, webhooks, cron, event-driven), Flue foi literalmente construído pra isso.

✅ Multi-cloud é requisito — Se você precisa rodar agentes em Cloudflare, AWS, GCP, ou on-premise sem reescrever, Flue é a opção com mais targets.

✅ Você já usa TypeScript — O DX é excelente pra quem vive em TS. Tipagem end-to-end, Vite, Zod, imports declarativos.

✅ Durabilidade importa — Se seus agentes rodam tasks longas (minutos) e não podem perder progresso, Durable Streams é a feature certa.

✅ Skills são centrais no seu workflow — Se você já usa o padrão SKILL.md (como nós fazemos aqui no homelab), Flue é o framework que trata isso como first-class citizen.

✅ Você quer componibilidade — Agentes → subagentes → tools → skills → MCP servers. Tudo se compõe sem gambiarras.

Quando NÃO usar

❌ Agentes simples que só precisam de um prompt e uma tool — Se é pergunta → resposta com uma API call no meio, Flue é canhão pra matar formiga. Use o Claude Agent SDK ou o Vercel AI SDK direto.

❌ Seu time é Python — Sem contorno. Flue é TypeScript-only. Vá de Pydantic AI, LangGraph ou CrewAI.

❌ Precisa de estabilidade absoluta — Em 1.0 Beta, breaking changes são esperados. Se seu produto em produção não tolera atualizações de framework, espere o 1.0 stable.

❌ Experiência interativa no terminal — Flue é headless. Se você quer o developer interagindo com o agente num TUI à la Claude Code, use o Claude Code ou OpenCode diretamente.

❌ Precisa de execução paralela complexa (DAGs) — Se seu workflow é um grafo direcionado com fan-out/fan-in sofisticado, LangGraph é mais adequado. Flue é declarativo, não graph-based.

O Flue no Contexto do Ecossistema — Um Framework Que Conecta Tudo

Deixa eu ser pessoal por um momento. Acompanho o mercado de agent frameworks vs coding agents desde que a primeira versão do LangChain apareceu, e o Flue é o primeiro framework que me fez pensar: “isso foi feito por gente que constrói tools de verdade”.

Não é só a qualidade técnica — é a coerência filosófica. O time do Astro entende que:

1. Agentes são infra, não produto — Ninguém quer ficar babando terminal. Agentes precisam rodar em background, sem TUI.
2. Skills são documentação executável — Markdown é legível, versionável, portável. Não é JSON schema opaco.
3. Lock-in é dívida técnica — Runtime-agnostic de verdade, não “funciona em qualquer lugar se você usar nosso provider”.
4. Crashes são normais — Em vez de fingir que agentes nunca morrem, design para recovery.

Isso é a mesma filosofia por trás do conceito de harness e loop: separar preocupações. O modelo raciocina. O harness executa. O framework dá DX. A plataforma dá durabilidade.

E tem a ironia deliciosa de que este blog é feito com Astro. O time que construiu a ferramenta com que publicamos este texto agora construiu a ferramenta com que os agentes que automatizam nosso workflow rodam. É o mesmo DNA, aplicado a domínios diferentes.

Pacotes do Ecossistema

Deploy targets integrados:

• Node.js (Hono server)
• Cloudflare Workers (Durable Objects)
• GitHub Actions
• GitLab CI/CD
• Docker / Railway / Fly / Render
• Daytona (sandbox remoto)

Deploy na Prática

Node.js (qualquer VM/container)

npx flue build --target node
PORT=8080 node dist/server.mjs

Cloudflare Workers

// flue.config.ts
export default defineConfig({
  target: 'cloudflare',
});

npx flue build --target cloudflare
npx wrangler deploy

Cada agente vira um Durable Object com storage isolado. Scale infinito, sem provisioning.

GitHub Actions

# .github/workflows/triage.yml
name: Issue Triage
on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx flue run triage --input '${{ toJSON(github.event.issue) }}'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Próximos Passos

Se este guia te convenceu a explorar:

1. Comece pelo README oficial → github.com/withastro/flue
2. Leia o SKILL.md concept → Entenda como skills markdown evitam o inferno de instruções gigantes
3. Entenda o harness por baixo → Nosso guia do Pi explica o motor que roda sob o Flue
4. Compare com outros frameworks → Agent frameworks vs coding agents te dá o mapa completo
5. Deploy em Cloudflare → O post da Cloudflare explica a integração nativa
6. Junte com MCP → Ferramentas, tools e MCP servers mostra como conectar tudo

A Opinião do Cronista

Vou ser direto: o Flue me empolgou mais do que qualquer framework de agentes nos últimos 6 meses. E olha que vi muita coisa passar — CrewAI, LangGraph, OpenAI Agents SDK, Claude Agent SDK, Eve.

O motivo é simples: é o primeiro que não me pede pra escolher entre DX e poder. Não preciso sacrificar tipagem pra ganhar flexibilidade. Não preciso aceitar vendor lock-in pra ter durabilidade. Não preciso abandonar TypeScript pra ter multi-agent.

É beta? É. Vai ter breaking changes? Vai. A comunidade é pequena? É.

Mas o time do Astro tem um track record impecável de levar projetos de beta a standard da indústria. Astro fez isso com meta-frameworks web. Aposto que Flue vai fazer o mesmo com agent frameworks.

Se você escreve TypeScript, constrói agentes que rodam em background, e quer durabilidade sem lock-in — instale hoje, mesmo que só pra experimentar. Esse é o framework que daqui a 12 meses todo mundo vai estar usando.

Este blog é construído com Astro — do mesmo time que criou o Flue. Skills markdown são first-class citizens tanto aqui quanto no framework. O futuro dos agentes é declarativo, durável, e sem lock-in.

→ Acompanhe mais guias técnicos sobre agentes IA em ft.ia.br