227 lines
11 KiB
Markdown
227 lines
11 KiB
Markdown
# Agently 官方技能包
|
||
|
||
`AI框架` `编程智能体` `技能安装` `工作流编排` `LLM应用`
|
||
|
||
# Agently Skills
|
||
|
||
面向编程智能体、与 Agently 配合使用的官方可安装技能包。
|
||
|
||
主框架仓库：<https://github.com/AgentEra/Agently>
|
||
官方文档：<https://agently.tech/docs/en/> | <https://agently.cn/docs/>
|
||
|
||
## 什么是 Agently？
|
||
|
||
Agently 是一个用于构建模型驱动应用和工作流的框架。
|
||
|
||
它原生支持以下能力：
|
||
|
||
- 异步优先的模型请求、流式消费与 Web 服务集成
|
||
- 模型配置与提供商设置
|
||
- 提示词组合与提示词配置
|
||
- 结构化输出与必填字段校验
|
||
- 响应复用、元数据访问与流式消费
|
||
- 工具、MCP、记忆与知识库流程
|
||
- 通过 TriggerFlow 实现工作流编排
|
||
- 通过 `agently-devtools` 提供可选的开发者工具支持
|
||
|
||
## 什么是 Agently-Skills？
|
||
|
||
Agently-Skills 是面向编程智能体、用于基于 Agently 进行构建的官方技能包。
|
||
|
||
它不仅仅解释 API 语法，还能教会编程智能体：
|
||
|
||
- 如何从自然语言产品需求中识别适合使用 Agently 的场景
|
||
- 如何选择合适的技能或技能组合
|
||
- 如何围绕 Agently 原生能力边界构建项目结构
|
||
- 如何应用最佳实践的项目布局、编排方式与性能重构
|
||
- 如何遵循 Agently 的设计哲学，而不是先写通用胶水代码
|
||
|
||
目标不是生成浅层的代码片段，而是帮助编程智能体产出一个真正契合 Agently 的完整项目。
|
||
|
||
例如，`基于本地 Ollama 构建一个旅行规划工具` 这样宽泛的需求，不应被简单视为一次本地模型调用。技能包应帮助编程智能体从这段自然语言意图中，决定正确的配置路径、提示词结构、工作流形态与项目布局。
|
||
|
||
## 为什么使用官方技能包？
|
||
|
||
- 提升对宽泛、欠规格的模型应用需求的场景识别能力。
|
||
- 编码了 Agently 原生最佳实践，而非框架无关的通用习惯。
|
||
- 包含项目布局、路由、性能优化与设计哲学的指导。
|
||
- 已针对真实场景语言进行校验，而不仅依赖手写代码片段。
|
||
|
||
## 路由模型
|
||
|
||
选择技能时，请参考以下思维模型：
|
||
|
||
- 如果需求来自业务目标、产品行为、重构意图，或所有者层级尚不明确，从 `agently-playbook` 开始。
|
||
- 如果需求已经足够具体明确，直接路由到对应的叶子技能。
|
||
- 优先使用 Agently 原生接口，而非自定义封装、自定义解析器、自定义重试循环或自定义工作流基础设施。
|
||
|
||
最重要的路由规则如下：
|
||
|
||
- 未明确的产品、助手、自动化或工作流需求 → `agently-playbook`
|
||
- 提供商接入、环境变量或模型设置分离 → `agently-model-setup`
|
||
- 提示词结构、提示词配置、YAML 驱动的提示词行为或配置文件提示词桥接 → `agently-prompt-management`
|
||
- 稳定的结构化字段、必填键或机器可读输出 → `agently-output-control`
|
||
- 将一个响应复用为文本、数据、元数据或流式更新 → `agently-model-response`
|
||
- 会话持续性或重启后恢复 → `agently-session-memory`
|
||
- 工具、MCP、FastAPIHelper、`auto_func`、`KeyWaiter`、通过 Playwright 或 PyAutoGUI 浏览，或可选的 `agently-devtools` 集成 → `agently-agent-extensions`
|
||
- 嵌入、索引、检索或知识库问答 → `agently-knowledge-base`
|
||
- 显式编排、TriggerFlow、混合同步/异步执行、事件驱动扇出、流程清晰度重构、图友好的工作流定义或可恢复的多阶段流程 → `agently-triggerflow`
|
||
- 从 LangChain 或 LangGraph 迁移 → `agently-migration-playbook`，再路由到对应的迁移叶子技能
|
||
|
||
异步通常应作为默认执行姿态：
|
||
|
||
- 对服务代码、流式传输、TriggerFlow、工具并发以及任何可能受益于并行或取消的路径，优先使用异步 API
|
||
- 将同步 API 视为本地脚本、教学示例或兼容桥接的便捷封装
|
||
- 如果方案将运行在 HTTP、SSE、WebSocket 或长驻 Worker 之后，默认假设异步优先，除非有具体约束证明不适用
|
||
|
||
## 标准项目结构
|
||
|
||
当 Agently 项目需要保持可维护性时，应围绕明确的能力边界进行初始化或重构，而不是将所有内容塞进一个臃肿的 `app.py`。
|
||
|
||
默认结构通常应分离以下部分：
|
||
|
||
- `SETTINGS.yaml` 或配置层：用于提供商配置、`${ENV.xxx}` 占位符、工作流/搜索/浏览参数及其他部署时开关
|
||
- `app/` 或集成层：加载配置、按需校验必填环境变量名、选择异步边界、接入工具与主流程
|
||
- `prompts/`：存放 YAML 或 JSON 提示词契约，包含 `input`、`info`、`instruct` 和 `output`
|
||
- `services/`：请求封装、响应归一化和面向业务的适配器
|
||
- `domain/` 或 `schemas/`：枚举、请求/响应契约和共享值对象
|
||
- `workflow/`：TriggerFlow 图及其 chunk 实现
|
||
- `tools/`：可替换的搜索、浏览、MCP 或外部适配器
|
||
- `tests/`：配置冒烟测试、提示词/响应检查以及 API 或流程验证
|
||
- `outputs/` 和 `logs/`：运行时产物，不与源码目录混放
|
||
- 可选的 `agently-devtools` 接入，位于集成层，用于本地观测、评估、Playground 与日志
|
||
|
||
以下两个有源码支撑的细节非常重要：
|
||
|
||
- Configure Prompt 支持跨提示词值和键的递归占位符映射。将 `${topic}`、`${language}`、`${column_title}` 等变量保留在提示词文件中，并通过 `load_yaml_prompt(..., mappings={...})` 或 `load_json_prompt(...)` 注入。
|
||
- 模型设置可保留 `${ENV.NAME}` 占位符，并通过 `Agently.load_settings("yaml_file", "...", auto_load_env=True)` 自动查找并加载本地 `.env` 文件进行解析。若以内联方式创建配置而非使用文件，请使用 `Agently.set_settings(...)`。
|
||
|
||
以下两条高频规则可防止常见偏差：
|
||
|
||
- 将稳定的共享输出契约保留在提示词配置中，而不是分散在各处的 Python 辅助函数里
|
||
- 将 `OpenAICompatible` 及类似提供商的设置放在请求方实际读取的插件命名空间下，例如 `plugins.ModelRequester.OpenAICompatible.*`
|
||
- 将可选的 DevTools 端点和桥接代码放在提示词文件和工作流辅助函数之外；使用 `agently-devtools` 公开包中的 `ObservationBridge`、`EvaluationBridge` 或 `create_local_observation_app(...)`，而不是仓库特定的安装指引
|
||
|
||
这是 `Agently-Daily-News-Collector` 所采用的模式：配置保留在 `SETTINGS.yaml`，提示词契约保留在 `prompts/`，流程构建保留在 `workflow/`，应用层负责环境加载与 Agently 接入。
|
||
|
||
项目初始化不应作为单独的公开技能，它属于 `agently-playbook` 的职责范围：确定所有者层级，创建项目骨架，再将具体实现工作交给对应的叶子技能。
|
||
|
||
更完整的公开参考见 [`skills/agently-playbook/references/project-framework.md`](skills/agently-playbook/references/project-framework.md)。
|
||
|
||
## 公开目录
|
||
|
||
公开目录目前包含 12 个技能。
|
||
|
||
### 入口
|
||
|
||
- `agently-playbook`
|
||
面向未明确的模型驱动产品、助手、内部工具、自动化、评估器、工作流或项目结构重构需求的顶层路由器。
|
||
|
||
### 请求侧
|
||
|
||
- `agently-model-setup`
|
||
提供商连接、基于 dotenv 的配置、模型传输设置及基于配置文件的模型分离。
|
||
- `agently-prompt-management`
|
||
提示词组合、提示词配置、YAML 驱动的提示词行为、映射及可复用的请求侧提示词结构。
|
||
- `agently-output-control`
|
||
输出模式、字段排序、必填键与结构化输出可靠性。
|
||
- `agently-model-response`
|
||
`get_response()`、解析结果、元数据、流式消费与响应复用。
|
||
- `agently-session-memory`
|
||
基于会话的持续性、备忘录、恢复与请求侧对话状态。
|
||
|
||
### 请求扩展
|
||
|
||
- `agently-agent-extensions`
|
||
工具、MCP、FastAPIHelper、`auto_func`、`KeyWaiter`、通过 Playwright 或 PyAutoGUI 浏览，以及可选的 `agently-devtools` 集成。
|
||
- `agently-knowledge-base`
|
||
嵌入向量加 Chroma 支持的索引、检索与检索问答流程。
|
||
|
||
### 工作流
|
||
|
||
- `agently-triggerflow`
|
||
TriggerFlow 编排、运行时状态、运行时流、工作流侧模型执行、事件驱动扇出、流程清晰度重构、混合同步/异步编排，以及便于调试和可视化的图友好工作流定义。
|
||
|
||
## 可选伴随包
|
||
|
||
Agently `v4.0.9` 还引入了 `agently-devtools` 作为可选的开发者工具伴随包。
|
||
|
||
- 安装：`pip install -U agently agently-devtools`
|
||
- 兼容说明：`agently-devtools 0.1.x` 对应 `agently >=4.0.9,<4.1.0`
|
||
- 公开入口点：`ObservationBridge`、`EvaluationBridge`、`EvaluationRunner` 和 `create_local_observation_app`
|
||
- 推荐启动方式：`agently-devtools start`
|
||
|
||
当 Agently 应用在开发和调试阶段需要本地运行时观测、评估、日志或 Playground 支持时，使用此包。技能包将其视为可选扩展接口，而非必须的源码仓库依赖。
|
||
|
||
### 迁移
|
||
|
||
- `agently-migration-playbook`
|
||
面向现有 LangChain 或 LangGraph 系统的迁移路由器。
|
||
- `agently-langchain-to-agently`
|
||
LangChain 智能体侧的直接迁移指导。
|
||
- `agently-langgraph-to-triggerflow`
|
||
LangGraph 编排的直接迁移指导。
|
||
|
||
## 安装
|
||
|
||
在所有检测到的智能体上最快速的全量安装：
|
||
|
||
```bash
|
||
npx skills add AgentEra/Agently-Skills --all
|
||
```
|
||
|
||
当需要显式控制目标智能体时，更安全的全量安装方式：
|
||
|
||
```bash
|
||
npx skills add AgentEra/Agently-Skills --agent codex --skill '*' -y
|
||
```
|
||
|
||
你也可以直接让编程智能体安装 `AgentEra/Agently-Skills`。
|
||
|
||
如果只需要安装部分技能，从 `agently-playbook` 开始：
|
||
|
||
```bash
|
||
npx skills add AgentEra/Agently-Skills --skill agently-playbook
|
||
```
|
||
|
||
`request-core`
|
||
适用于方案停留在请求侧、需要模型配置、提示词塑形、结构化输出与响应复用的场景。
|
||
|
||
```bash
|
||
npx skills add AgentEra/Agently-Skills --skill agently-playbook
|
||
npx skills add AgentEra/Agently-Skills --skill agently-model-setup
|
||
npx skills add AgentEra/Agently-Skills --skill agently-prompt-management
|
||
npx skills add AgentEra/Agently-Skills --skill agently-output-control
|
||
npx skills add AgentEra/Agently-Skills --skill agently-model-response
|
||
```
|
||
|
||
`request-extensions`
|
||
适用于请求侧还需要工具、MCP、会话持续性或知识库的场景。
|
||
|
||
```bash
|
||
npx skills add AgentEra/Agently-Skills --skill agently-playbook
|
||
npx skills add AgentEra/Agently-Skills --skill agently-agent-extensions
|
||
npx skills add AgentEra/Agently-Skills --skill agently-session-memory
|
||
npx skills add AgentEra/Agently-Skills --skill agently-knowledge-base
|
||
```
|
||
|
||
`workflow-core`
|
||
适用于所有者层级为工作流编排、尤其是事件驱动扇出、性能敏感重构、可恢复流程或混合同步/异步执行的场景。
|
||
|
||
```bash
|
||
npx skills add AgentEra/Agently-Skills --skill agently-playbook
|
||
npx skills add AgentEra/Agently-Skills --skill agently-triggerflow
|
||
npx skills add AgentEra/Agently-Skills --skill agently-output-control
|
||
npx skills add AgentEra/Agently-Skills --skill agently-model-response
|
||
npx skills add AgentEra/Agently-Skills --skill agently-session-memory
|
||
```
|
||
|
||
`migration`
|
||
适用于明确需要将现有 LangChain 或 LangGraph 系统迁移至 Agently 的场景。
|
||
|
||
```bash
|
||
npx skills add AgentEra/Agently-Skills --skill agently-playbook
|
||
npx skills add AgentEra/Agently-Skills --skill agently-migration-playbook
|
||
npx skills add AgentEra/Agently-Skills --skill agently-langchain-to-agently
|
||
npx skills add AgentEra/Agently-Skills --skill agently-langgraph-to-triggerflow
|
||
``` |