Agently 文档

中文

English

中文

English

Appearance

扩展边界 ​

Agently 的扩展能力按层组织。应用开发者通常只碰最上层入口；只有在做自定义 Action、托管环境、插件或框架扩展时，才需要往下看。

text
Foundation capabilities
  ModelRequest / Action / ExecutionEnvironment / Workspace / Recall / RuntimeEvent
    -> TriggerFlow execution lifecycle
    -> TaskDAG / AdaptiveLoop / BootstrapLoop
    -> AgentExecution / SkillsExecution / DynamicTask
    -> business application

这条线能帮团队判断一个新能力应该放在哪：稳定协议由 foundation capabilities 表达，可替换实现放在 plugin/provider，常见能力用 built-in action 提供，面向应用的快捷入口交给 Agent facade、Agent Component 或 helper。AgentTaskLoop、DynamicTask 和 SkillsExecution 属于 AgentExecution 之上的策略或应用封装，不应变成新的平行运行体系。

先看自己是哪类开发者 ​

你在做优先使用少碰什么
业务应用agent.define(...)、AgentExecution、agent.use_actions(...)、agent.use_mcp(...)、built-in actions、enable_* helpersmanager/provider 内部 API
自定义 Action@agent.action_func、agent.use_actions(...)、Action schema在 action 内私自启动长期资源
托管执行资源Execution Environment Provider把资源生命周期塞进业务 handler
框架插件Protocol、plugin contract、runtime event绑定某个应用的语法糖
架构扩展core data types、dispatch、lifecycle contract把业务专用行为放进 core

普通应用开发多数只需要 AgentExecution、Actions、Workspace、TriggerFlow、Dynamic Task 和 Services 文档。扩展边界页主要给做平台化、插件化或团队公共能力的人读。

Action 负责“能调用什么” ​

Action 是模型或 Agent 可调用的能力面。它回答三件事：

  • 名字和描述是什么。
  • 输入 schema 是什么。
  • 一次调用返回什么结构。

一个普通函数可以直接成为 Action：

python
@agent.action_func
def lookup_ticket(ticket_id: str) -> dict:
    return {"ticket_id": ticket_id, "status": "open"}

只要能力是一次性、无状态、没有复杂生命周期，Action 层就够了。

Execution Environment 负责“运行前要准备什么” ​

有些 Action 背后需要 live dependency：MCP server、浏览器、SQLite、Node.js runner、Python sandbox、Docker、远端执行器。此时生命周期不应该藏在 Action 函数里。

Execution Environment 负责：

  • 启动或复用资源。
  • 做健康检查。
  • 管理 scope 和引用计数。
  • 处理 approval、policy 和 cleanup。
  • 把 ready handle 注入到运行期。

Action 仍然是模型可见的调用面；Execution Environment 是执行前后的资源管理面。

Built-in Actions 是默认能力目录 ​

Agently 内置能力以 Actions 形式暴露，例如：

  • Python / Bash / Node.js 执行
  • workspace 文件搜索、读取、写入
  • Search / Browse
  • SQLite
  • MCP tools
  • 已注册 Python 函数

新的内置能力应放在 agently.builtins.actions 这条 authoring/import 路径上。agently.builtins.tools 只是兼容旧代码的薄 facade，不是新能力的设计入口。

Agent Component 给应用一个简单入口 ​

应用开发者不应该理解每个 provider handle 的生命周期。Agent Component 或 helper 把常见能力包装成表达意图的 API：

python
agent.enable_python(...)
agent.enable_shell(...)
agent.enable_workspace_file_actions(...)
agent.enable_nodejs(...)
agent.enable_sqlite(...)

这类入口负责把 built-in actions、policy、prompt guidance 和 environment requirements 组合起来，让业务代码只表达“我要开放这个能力”。

Skills 不应该变成第二套执行器 ​

Skill package 可以包含 guidance、scripts、MCP assets、resources 或 workflow templates。它应该把这些内容映射到已有 Agently 层：

Skill 内容落到 Agently 哪层
guidanceprompt / context
scriptsPython、Bash、Node.js 等 built-in actions
MCP assetsMCP actions 和 environment requirements
hooks经过审批的 actions 或 sandbox-backed executors
workflow templatesTriggerFlow templates
resource dependenciesresource providers 或 execution-local handles

这样 Skills 负责打包和选择，不会和 Action Runtime、TriggerFlow 并列成另一套 runtime。

Typing 也是扩展契约 ​

公开 API 的有限选项应尽量用 Literal，结构化 payload 用 TypedDict 或 dataclass，插件契约用 Protocol。类型不是装饰，它能让 IDE、coding agent 和测试更早发现错误。

运行时校验仍然要保留，因为很多调用来自动态配置或模型输出。

判断一句话 ​

如果这是模型能调用的一次操作，先看 Action。如果这是操作背后的 live 资源生命周期，看 Execution Environment。如果这是常见能力的用户友好入口，看 Agent Component。如果这是可替换后端，看 plugin/provider。如果它是稳定数据结构或生命周期协议，才进入 core。

另见 ​