flue-framework

npm install @flue/runtime valibot@^1.0.0
npm install --save-dev @flue/cli typescript
npx flue init --target node

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

export default createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  instructions: 'Tell a funny hello world engineering joke.',
}));

npx flue connect hello-world --target node --env .env

// src/agents/social-search.ts
import { createAgent, defineTool, Type, local } from '@flue/runtime';
import type { AgentRouteHandler, AgentWebSocketHandler } from '@flue/runtime';

const myTool = defineTool({
  name: 'my_tool',
  description: 'Does something useful',
  parameters: Type.Object({
    query: Type.String({ description: 'Search query' }),
  }),
  execute: async ({ query }) => {
    return JSON.stringify({ result: query });
  },
});

const agent = createAgent(() => ({
  model: 'deepseek/deepseek-v4-flash',
  instructions: 'You are a helpful assistant.',
  sandbox: local(),
  tools: [myTool],
}));

// These exports are REQUIRED for HTTP/WS access
export const route: AgentRouteHandler = agent.route;
export const websocket: AgentWebSocketHandler = agent.websocket;
export default agent;

// src/workflows/keyword-search.ts
import { createAgent, type FlueContext } from '@flue/runtime';
import * as v from 'valibot';

async function handler({ init, payload, env }: FlueContext) {
  const agent = createAgent(() => ({
    model: env.MODEL || 'deepseek/deepseek-v4-flash',
    instructions: 'Search for keywords and return structured results.',
  }));

  const harness = await init(agent);
  const session = await harness.session();

  const result = await session.prompt(
    `Search for: ${payload.keyword}`,
    { result: v.object({ items: v.array(v.string()) }) },
  );

  return result;
}

export default handler;

// ❌ WRONG — init() does NOT accept a plain config object
const harness = await init({
  model: 'deepseek/deepseek-v4-flash',
  instructions: '...',
  providers: { deepseek: { apiKey: '...' } },
});

// ✅ CORRECT — init() requires a createAgent() result
const agent = createAgent(() => ({
  model: 'deepseek/deepseek-v4-flash',
  instructions: '...',
}));
const harness = await init(agent);

// ✅ init() second parameter is AgentHarnessOptions { name, tools, skills, subagents }
const harness = await init(agent, {
  tools: [myTool],
  subagents: [researcherProfile],
});

# .env
DEEPSEEK_API_KEY=sk-your-key
MODEL=deepseek/deepseek-v4-flash

// In createAgent — just use the model specifier
const agent = createAgent(() => ({
  model: env.MODEL || 'deepseek/deepseek-v4-flash',
  instructions: '...',
}));

// ✅ Provider overrides go in createAgent
const agent = createAgent(() => ({
  model: 'anthropic/claude-haiku-4-5',
  instructions: '...',
  // providers config is NOT available here in current version
}));

// For DeepSeek via Anthropic-compatible endpoint, set env vars:
// ANTHROPIC_API_KEY=sk-your-deepseek-key
// ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic

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

registerProvider('my-provider', {
  api: 'openai-completions',
  baseUrl: 'https://my-provider.example.com/v1',
  apiKey: process.env.MY_PROVIDER_API_KEY,
  models: { 'my-model': { maxTokens: 8192 } },
});

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

const myTool = defineTool({
  name: 'http_request',
  description: 'Make an HTTP request',
  parameters: Type.Object({
    method: Type.Union([Type.Literal('GET'), Type.Literal('POST')]),
    url: Type.String({ description: 'Target URL' }),
    body: Type.Optional(Type.String({ description: 'POST body as JSON string' })),
  }),
  execute: async ({ method, url, body }) => {
    // execute() must return Promise<string>
    const result = await fetch(url, { method, body });
    return JSON.stringify(await result.json());
  },
});

// ✅ Direct Node.js HTTP in defineTool — no sandbox needed
import https from 'node:https';

execute: async ({ path }) => {
  return new Promise((resolve) => {
    const req = https.request({ hostname: 'api.example.com', path }, (res) => {
      let data = '';
      res.on('data', (chunk) => (data += chunk));
      res.on('end', () => resolve(data));
    });
    req.end();
  });
}

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

export const researcher = defineAgentProfile({
  name: 'researcher',
  description: 'Deep data collection agent with pagination support',
  instructions: 'You are a data collection specialist...',
});

import { researcher } from '../shared/profiles/researcher';

const agent = createAgent(() => ({
  model: 'deepseek/deepseek-v4-flash',
  instructions: '...',
  subagents: [researcher],
}));

import { local } from '@flue/runtime/node';

const agent = createAgent(() => ({
  model: 'deepseek/deepseek-v4-flash',
  instructions: '...',
  sandbox: local(), // Access host filesystem, Python, curl, etc.
}));

my-project/
├─ src/
│  ├─ agents/
│  │  └─ social-search.ts     ← agent "social-search"
│  ├─ workflows/
│  │  └─ keyword-search.ts    ← workflow "keyword-search"
│  ├─ shared/
│  │  ├─ tools/               ← defineTool modules
│  │  ├─ profiles/            ← defineAgentProfile modules
│  │  └─ constants.ts
│  └─ app.ts                  ← Entry point (Hono + flue routes)
├─ public/
│  └─ index.html              ← Web chat frontend
├─ .env
├─ package.json
└─ flue.config.ts

import { flue } from '@flue/runtime/routing';
import { Hono } from 'hono';
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';

const app = new Hono();

// Custom routes BEFORE flue()
app.get('/', (c) => {
  const html = readFileSync(resolve(process.cwd(), 'public', 'index.html'), 'utf-8');
  return c.html(html);
});

// Mount Flue agent routes
app.route('/', flue());

export default app;

curl -N -X POST http://localhost:3583/agents/social-search/my-session \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message":"微博热搜Top3"}'

{
  "result": { "text": "## 微博热搜 Top 5\n..." },
  "usage": { "input": 9598, "output": 717, "totalTokens": 23627 },
  "model": { "provider": "deepseek", "id": "deepseek-v4-flash" }
}

// Without result → returns { text: string }
const response = await session.prompt('Hello');
console.log(response.text);

// With result → returns parsed valibot data DIRECTLY (not wrapped)
const result = await session.prompt('2+2?', {
  result: v.object({ answer: v.number() }),
});
console.log(result.answer); // Direct access, NOT result.data.answer

// ✅ Include JSON format hint for DeepSeek
await session.prompt(
  'What is 2 + 2? Respond as JSON: {"answer": 4}.',
  { result: v.object({ answer: v.number() }) },
);

// Delegate to sub-agent — also returns data directly with result schema
const data = await session.task('Research this topic', {
  agent: 'researcher',
  result: v.object({ findings: v.array(v.string()) }),
});

// ❌ WRONG
await harness.fs.writeFile('/file.md', content);

// ✅ CORRECT
await harness.env.writeFile('/file.md', content);
await harness.env.readFile('/file.md');
await harness.env.exists('/file.md');
await harness.env.mkdir('/dir', { recursive: true });
await harness.env.readdir('/dir');
await harness.env.rm('/file');
await harness.env.cwd;

npm run build   # Build to dist/
npm start       # Start production server

{
  "scripts": {
    "start": "bash -c 'set -a && source .env && set +a && PORT=3583 node dist/server.mjs'"
  }
}

node --version    # Must be >= 22.18.0
npm ls valibot    # Must show 1.x.x

npx flue run <agent-name> --target node --payload '<json>' --env ".env"

import { createAgent, defineTool, Type, local } from '@flue/runtime';
import type { AgentRouteHandler, AgentWebSocketHandler } from '@flue/runtime';

const apiCall = defineTool({
  name: 'api_call',
  description: 'Call an external API',
  parameters: Type.Object({
    method: Type.Union([Type.Literal('GET'), Type.Literal('POST')]),
    path: Type.String({ description: 'API path' }),
    params: Type.Optional(Type.Record(Type.String(), Type.String())),
  }),
  execute: async ({ method, path, params }) => {
    // Direct Node.js https request — no Python/shell needed
    return JSON.stringify({ method, path, params });
  },
});

const agent = createAgent(() => ({
  model: 'deepseek/deepseek-v4-flash',
  instructions: `You are a social media search assistant.
Analyze user intent, call appropriate APIs, and return results.

When asked for structured data, always respond with valid JSON.`,
  sandbox: local(),
  tools: [apiCall],
}));

export const route: AgentRouteHandler = agent.route;
export const websocket: AgentWebSocketHandler = agent.websocket;
export default agent;

const res = await fetch(`/agents/social-search/${sessionId}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify({ message: userInput }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  const lines = buf.split('\n');
  buf = lines.pop();
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const evt = JSON.parse(line.slice(6));
      // evt.type: thinking_start, tool_execution_start, text_delta, etc.
      handleEvent(evt);
    }
  }
}