Lesson 0004 · 12–18 min

Tools、Skills、Actions：三种“能力”的边界

今天只学一个技能：当你想给 Flue agent 增加能力时，能判断应该用 Tool、Skill 还是 Action。

目标：能力分类核心：边界感练习：场景判断

1. 三句话先分清

Flue 的 agent harness 可以装很多“能力”。最容易混的是 Tool、Skill、Action。先记这张表：

概念一句话问自己的问题
Tool让模型调用你的应用代码，查数据或做受控动作。“它需要执行一个直接函数吗？”
Skill给模型可复用的说明、流程、参考资料。“它需要学会一套做法吗？”
Action一段可复用、带 schema、由应用控制步骤的 agent-backed operation。“它需要稳定复用一段多步任务吗？”
记忆钩子：Tool = 手；Skill = 手册；Action = 标准作业流程。

2. Tool：应用代码能力

官方定义里，Tool 用来让 agent 在工作时检索信息或执行动作，比如查订单、创建 ticket、批准请求。Tool 会执行你的 application code。

import { defineTool } from '@flue/runtime';
import * as v from 'valibot';

export const lookupOrderStatus = defineTool({
  name: 'lookup_order_status',
  description: 'Look up the current fulfillment status for one order ID.',
  input: v.object({ orderId: v.string() }),
  output: v.object({ status: v.nullable(v.string()) }),
  async run({ input, signal }) {
    return { status: await orders.getStatus(input.orderId, { signal }) };
  },
});

安全边界：Tool 的参数是模型选择的输入，不是授权边界。你的应用要先决定 agent 可以访问哪个 customer/account/repository，再让模型只在这个边界内选择参数。

Source: Flue Tools guide.

3. Skill：可复用指导

Skill 不给 agent 新的执行能力。它提供的是 reusable instructions 和 supporting resources：比如代码审查流程、事故排查 checklist、项目规范、论文阅读方法。

import { defineAgent } from '@flue/runtime';
import review from '../skills/review/SKILL.md' with { type: 'skill' };
import triage from '../skills/triage/SKILL.md' with { type: 'skill' };

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  skills: [review, triage],
}));

Skill 适合

流程、规范、专业方法、checklist、参考文档。

Skill 不适合

查数据库、发请求、写入外部系统、授权敏感动作。

Source: Flue Skills guide.

4. Action：可复用 operation

Action 是可复用的 agent-backed operation。它有 name、description、input、output、run，很像你上一课看到的 Workflow 结构；区别是 Action 本身不会自动被发现，只有被 import 到 workflow 或 agent 配置里才可用。

import { defineAction } from '@flue/runtime';
import * as v from 'valibot';

export const summarize = defineAction({
  name: 'summarize_document',
  description: 'Summarize a document clearly and concisely.',
  input: v.object({ text: v.string() }),
  output: v.object({ summary: v.string() }),
  async run({ harness, input, log }) {
    log.info('Summarizing document');
    const session = await harness.session();
    const response = await session.prompt(`Summarize this text:\n\n${input.text}`);
    return { summary: response.text };
  },
});
怎么使用 Action效果
绑定到 defineWorkflow({ action })把它作为可检查的 workflow run 来调用；run/result/events 归在 workflow 下。
加入 agent 的 actions: [...]模型可以决定什么时候调用它；Flue 会把它作为 framework-managed tool 呈现给模型。

Source: Flue Actions guide.

5. 别把 Sandbox 混进 Tool

还有一个常见误区：文件和命令能力不是一定要做成 custom tool。Flue 的 Sandbox 给 agent 一个 workspace，可以读写文件、运行命令。Tool 更适合“调用应用服务/数据层”。

判断句：要操作工作区文件或命令 → 看 Sandbox；要查你应用里的订单/账号/数据库 → 看 Tool。

Source: Flue Sandboxes guide.

6. 练习：选 Tool / Skill / Action

先自己答：下面场景应该优先用什么？

  1. 让客服 agent 查询当前客户某个订单状态。
  2. 让代码审查 agent 每次都按公司 review checklist 做审查。
  3. “总结文档”这件事既要作为 workflow 跑，也要让 agent 在对话中复用。
  4. 让 agent 在临时 workspace 里读写 document.md 和 review.md。
查看参考答案
  1. Tool：调用受控应用代码查订单。
  2. Skill：复用 review 方法和 checklist。
  3. Action：复用一段带 input/output/run 的 operation，并可绑定 workflow/agent。
  4. Sandbox：这是 workspace 文件能力，不必先写 custom tool。

小测验

哪一项最适合描述 Skill？

再来一题

什么时候更应该考虑 Action，而不是普通 Tool？

本课结束后你应该能说出

  • Tool 执行 application code；Skill 提供 reusable instructions；Action 封装 reusable agent-backed operation。
  • Tool 参数不是授权边界，授权必须由应用控制。
  • Skill 不增加执行能力；不要把密钥、私钥、运行时 secrets 放进 skill directory。
  • Action 可以绑定到 workflow，也可以加入 agent 的 actions 列表。
  • 文件/命令 workspace 能力优先看 Sandbox，而不是强行写 Tool。

下一课建议：0005 — Sandbox：virtual、local、remote 的选择与风险。这会把 agent 的“能行动的环境”讲清楚。

有任何不清楚的地方，直接问我；我会按你的目标调整下一节课。

← Lesson 0003Capability Cheatsheet →
↑