Actions 概览
模型只回答文本时，request 层已经够用。问题从“回答”变成“做事”以后，就需要 Actions：查询数据、调用函数、访问 MCP tool、搜索网页、运行 Python 或把结果写回业务系统。
Action 是一次模型请求里的外部能力层。它负责让模型知道有哪些能力可以用、如何调用、如何记录调用结果。它不是长流程编排层。
先看一个最小函数 Action
from agently import Agently
agent = Agently.create_agent()
@agent.action_func
async def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
agent.use_actions([add])
result = (
agent
.input("Use the action to calculate 3333 + 6666.")
.output({"answer": (int, "calculation result", True)})
.get_result()
)
data = result.get_data()这段代码里，模型不是自己心算，而是在一次 request 中选择并调用 add。Action Runtime 负责把调用记录、执行结果和最终响应放回同一条执行链里。
Action 负责什么
| 层 | 负责 | 不负责 |
|---|---|---|
| Action | 把一个外部能力暴露给模型 | 工作流生命周期 |
| Action Runtime | 归一化 action call、分发执行、记录日志 | 分支、并发、暂停恢复 |
| Action Executor | 真正执行一次函数、MCP、沙箱或内置能力 | 选择业务流程下一步 |
| Execution Environment | 准备可复用资源，如 MCP server、浏览器、SQLite、Node.js、沙箱 | 业务任务规划 |
| TriggerFlow | 阶段、分支、并发、事件、等待、恢复 | tool schema 注册 |
判断很简单：如果只是“一次回答时需要调用能力”，用 Actions；如果应用要管理多个阶段和运行状态，用 TriggerFlow 把多个 request 或 action 调用编排起来。
工具多了以后，先治理能力面
一个函数 action 很容易接。真正上线时，工具会变成一组持续增长的能力目录：查询类、写入类、MCP tools、浏览、搜索、脚本、沙箱和业务系统 adapter。这个时候不要把所有工具一次性塞给模型。
更稳的结构是四层：
| 层 | 负责什么 | 常见问题 |
|---|---|---|
| 注册 | 工具名、描述、参数 schema、副作用等级和 owner | 工具散在各处，无处可查 |
| 激活 | 按场景、身份、任务阶段裁剪本次可见工具 | 全量暴露导致选错、越权和成本上升 |
| 规划 | 模型或规则决定调用哪个工具、填什么参数 | 决策逻辑和执行函数耦合，无法灰度或回退 |
| 执行 | 本地函数、HTTP、MCP、沙盒都归一为一次 action result | 接入新类型就要改 planner |
Actions / Action Runtime 负责这条链路的调用面和记录面。ExecutionEnvironment 负责背后的 live resource 生命周期。TriggerFlow 负责把多次 request / action 调用放进可观察流程。
常见入口
本地函数
适合业务系统里已经有明确函数的场景，比如计算价格、查询订单、校验库存、格式化报表。
继续读：Action Runtime
内置能力
Agently 提供常见能力入口，例如 Python、shell、workspace file actions、Node.js、SQLite、Search、Browse 等。新项目优先从 Agent Component helpers 和 agently.builtins.actions 开始。
继续读：Action Runtime
MCP
如果能力已经以 MCP server 形式存在，可以把 MCP tool 装进 action surface，让模型在 request 期调用。
继续读：MCP
Execution Environment
当外部能力不是一个纯函数，而是需要启动、复用、健康检查或 policy 控制的资源，比如浏览器、SQLite、Node.js、Docker、MCP server，就进入 Execution Environment。
旧 tools 兼容
tool_func、use_tool、use_tools、extra.tool_logs 等旧入口仍可维护旧项目。新项目不要从这些别名开始。
继续读：工具兼容
Actions 和 TriggerFlow 怎么配合
Action 发生在 request 内，TriggerFlow 管流程。一个常见结构是：
TriggerFlow execution
├─ chunk A: 调 agent，agent 在 request 内调用 Actions
├─ chunk B: 根据结果分支
└─ chunk C: 推送 runtime stream 或等待人工确认如果只有一个 agent turn，Actions 就够了。如果要把多个 turn、业务检查、人工审批和恢复串起来，再加 TriggerFlow。
什么时候不要用 Action
- 只是把输入改写成文本，不需要外部能力。
- 只是 2-3 步确定性 Python 管道，用普通函数或 async 函数更清楚。
- 流程需要等待人工审批、外部事件或跨重启恢复。直接读 TriggerFlow 概览。
- 任务图本身来自模型规划或业务系统提交。直接读 Dynamic Task。
常见误用
- 把 Action 当成业务工作流。Action 只解决一次 request 里的能力调用。
- 把所有外部能力都写成一个巨大函数。更好的做法是拆成语义清楚、输入输出明确的 actions。
- 在 prompt 里描述“你可以假装查询订单”。真实业务能力应该通过 Action 或 mock 外部系统显式暴露。
- 新项目继续沿用旧 tools API。兼容可以保留，推荐入口应是 Action Runtime。
- 没有日志和结果读取就把 Action 接进生产。至少要能看到 action logs、模型最终结果和错误信息。
下一步
- 写函数 action 和使用内置能力：Action Runtime
- 接 MCP tool：MCP
- 管理可复用执行资源：Execution Environment
- 把多个 request 编排成流程：TriggerFlow 概览
- 把带 action 的 agent 暴露成服务：FastAPI 服务封装