# Agently 官方技能包 `AI框架` `编程智能体` `技能安装` `工作流编排` `LLM应用` # Agently Skills 面向编程智能体、与 Agently 配合使用的官方可安装技能包。 主框架仓库： 官方文档： | ## 什么是 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 ```