Agently Docs

English

中文

English

中文

Appearance

English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

扩展边界 ​

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。

另见 ​