mc-skills/catalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
catalog/repos/agentera--agently-skills.md

11 KiB
Raw Permalink Blame History

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。

公开目录

公开目录目前包含 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 编排的直接迁移指导。

安装

在所有检测到的智能体上最快速的全量安装：

npx skills add AgentEra/Agently-Skills --all

当需要显式控制目标智能体时，更安全的全量安装方式：

npx skills add AgentEra/Agently-Skills --agent codex --skill '*' -y

你也可以直接让编程智能体安装 AgentEra/Agently-Skills。

如果只需要安装部分技能，从 agently-playbook 开始：

npx skills add AgentEra/Agently-Skills --skill agently-playbook

request-core 适用于方案停留在请求侧、需要模型配置、提示词塑形、结构化输出与响应复用的场景。

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、会话持续性或知识库的场景。

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 适用于所有者层级为工作流编排、尤其是事件驱动扇出、性能敏感重构、可恢复流程或混合同步/异步执行的场景。

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 的场景。

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