Agently 4 🚀

更快地构建生产级 AI 应用，确保输出稳定且工作流易于维护。

英文介绍 | 中文介绍

---

🔥 最新文档 | 🚀 5分钟快速入门 | 💡 核心特性

---

官方技能

现已发布可安装的 Agently 官方技能，地址如下：

• GitHub：https://github.com/AgentEra/Agently-Skills
• 安装命令：npx skills add AgentEra/Agently-Skills

安装后您将获得：

• 针对实际 Agently 工作的更优实现路由，从单请求设计到 TriggerFlow、多智能体、MCP、工具、会话以及 FastAPI 集成
• 针对常见生产任务的即用型技能指南，无需在每次编码中重复解释框架概念
• LangChain 和 LangGraph 的迁移手册，帮助现有智能体系统更快迁移到 Agently
• 更高质量的编码智能体体验，因为技能包为智能体提供了具体的 Agently 模式、边界和推荐实现路径

---

📚 快速链接

• 文档（英文）：https://agently.tech/docs
• 文档（中文）：https://agently.cn/docs
• 智能体系统手册（英文）：https://agently.tech/docs/en/agent-systems/overview.html
• 智能体系统手册（中文）：https://agently.cn/docs/agent-systems/overview.html
• 官方 Agelyt 技能：https://github.com/AgentEra/Agently-Skills
• 安装 Agelyt 技能：npx skills add AgentEra/Agently-Skills

可选配套包：Agelyt Devtools

agently-devtools 是一个独立的配套包，用于运行时观测和开发者工具。

• 安装：pip install agently-devtools
• 依赖方向：agently-devtools -> agently
• 兼容性：agently-devtools 0.1.x 针对 agently >=4.0.9,<4.1.0
• 集成入口：ObservationBridge 和 create_local_observation_app

DevTools 包是可选的，不会在 agently 和 agently-devtools 之间形成反向依赖。

🤔 为什么选择 Agelyt？

许多 GenAI POC 在生产环境中失败，并非由于模型性能不足，而是因为缺少工程层面的控制：

常见挑战	Agelyt 如何帮助
输出模式漂移，JSON 解析失败	使用 output() + ensure_keys 实现“契约优先”的输出控制
工作流复杂且难以维护	使用 to / if / match / batch / for_each 进行 TriggerFlow 编排
多轮状态不稳定	使用 Session（v4.0.8.1+），支持会话激活、上下文窗口控制、自定义记忆策略及持久化
工具调用难以审计	通过 extra.tool_logs 记录工具日志
切换模型成本高昂	使用 OpenAICompatible 统一模型设置

Agelyt 将 LLM 的不确定性转化为稳定、可测试、易于维护的工程系统。

✨ 核心特性

1) 📝 契约优先的输出控制

使用 output() 定义结构，并通过 ensure_keys 强制确保关键字段。

result = (
    agent
    .input("分析用户反馈")
    .output({
        "sentiment": (str, "positive/neutral/negative"),
        "key_issues": [(str, "问题摘要")],
        "priority": (int, "1-5，5为最高")
    })
    .start(ensure_keys=["sentiment", "key_issues[*]"])
)

2) ⚡ 结构化流式处理（即时）

在生成时即可消费结构化字段。

response = (
    agent
    .input("解释递归并给出两条建议")
    .output({"definition": (str, "一句话"), "tips": [(str, "建议")]})
    .get_response()
)

for msg in response.get_generator(type="instant"):
    if msg.path == "definition" and msg.delta:
        ui.update_definition(msg.delta)
    if msg.wildcard_path == "tips[*]" and msg.delta:
        ui.add_tip(msg.delta)

3) 🧩 TriggerFlow 编排

可读性强、易于测试的工作流，支持分支和并发。

(
    flow.to(handle_request)
    .if_condition(lambda d: d.value["type"] == "query")
    .to(handle_query)
    .elif_condition(lambda d: d.value["type"] == "order")
    .to(check_inventory)
    .to(create_order)
    .end_condition()
)

4) 🧠 Session（多轮上下文，v4.0.8.1+）

内置 SessionExtension，支持 activate_session/deactivate_session、上下文窗口控制、自定义记忆策略以及 JSON/YAML 持久化。

from agently import Agently

agent = Agently.create_agent()

# 按用户激活会话（通过 session_id 复用）
agent.activate_session(session_id="demo_user_1001")

# 可选：按最大长度自动裁剪窗口
agent.set_settings("session.max_length", 12000)

# 可选：自定义策略（分析 -> 调整大小）
session = agent.activated_session
assert session is not None

def analysis_handler(full_context，context_window，memo，session_settings):
    if len(context_window) > 6:
        return "keep_last_six"
    return None

def keep_last_six(full_context，context_window，memo，session_settings):
    return None，list(context_window[-6:]），memo

session.register_analysis_handler(analysis_handler)
session.register_resize_handler("keep_last_six"，keep_last_six)

5) 🔧 工具调用 + 日志

工具的选择和使用会被记录在 extra.tool_logs 中。

@agent.tool_func
def add(a: int，b: int) -> int：
    return a + b

response = agent.input("12+34=?").use_tool(add).get_response()
full = response.get_data(type="all")
print(full["extra"]["tool_logs"])

6) 🌐 统一模型设置（OpenAI兼容）

一份配置即可适配多个服务商及本地模型。

from agently import Agently

Agently.set_settings(
    "OpenAICompatible",
    {
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-chat",
        "auth": "DEEPSEEK_API_KEY",
    },
)

🚀 快速入门

安装

pip install -U agently

要求：Python >= 3.10，推荐使用 Agently >= 4.0.7.2

5分钟示例

1. 结构化输出

from agently import Agently

agent = Agently.create_agent()

result = (
    agent.input("用一句话介绍 Python，并列出 2 个优点")
    .output({
        "introduction": (str, "一句话"),
        "advantages": [(str, "优点")]
    })
    .start(ensure_keys=["introduction", "advantages[*]"])
)

print(result)

2. 工作流路由

from agently import TriggerFlow, TriggerFlowEventData

flow = TriggerFlow()

@flow.chunk
def classify_intent(data: TriggerFlowEventData):
    text = data.value
    if "price" in text:
        return "price_query"
    if "feature" in text:
        return "feature_query"
    if "buy" in text:
        return "purchase"
    return "other"

@flow.chunk
def handle_price(_: TriggerFlowEventData):
    return {"response": "定价取决于具体方案..."}

@flow.chunk
def handle_feature(_: TriggerFlowEventData):
    return {"response": "我们的产品支持..."}

(
    flow.to(classify_intent)
    .match()
    .case("price_query")
    .to(handle_price)
    .case("feature_query")
    .to(handle_feature)
    .case_else()
    .to(lambda d: {"response": "您想了解什么呢？"})
    .end_match()
    .end()
)

print(flow.start("这个要多少钱？"))

✅ 您的应用已准备好上线吗？— 上线准备检查清单

基于使用 Agently 成功交付实际项目的团队经验，这份 生产就绪检查清单 可帮助您在发布前降低常见风险。

领域	检查项	推荐做法
📝 输出稳定性	关键接口是否稳定？	使用 output() 定义模式，并通过 ensure_keys 锁定关键字段。
⚡ 实时用户体验	生成过程中需要实时更新吗？	使用 type="instant" 的结构化流式事件进行消费。
🔍 可观测性	工具调用可审计吗？	检查 extra.tool_logs 获取完整的参数和结果。
🧩 工作流健壮性	复杂的工作流是否经过充分测试？	对每个 TriggerFlow 分支以及并发限制进行单元测试，确保输出符合预期。
🧠 内存与上下文	多轮交互体验是否一致？	定义会话/记忆摘要、裁剪及持久化策略。
📄 提示词管理	逻辑能否安全演进？	对提示词进行版本控制和配置，以追踪变更历史。
🌐 模型策略	是否可以切换或降级模型？	使用 OpenAICompatible 统一配置，实现快速服务商切换。
🚀 性能与规模	能否应对高并发场景？	在真实的 Web 服务场景中验证异步性能。
🧪 质量保证	回归测试是否完整？	为核心场景创建固定输入及预期输出的测试用例。

📈 谁正在使用 Agently 解决实际问题？

“Agently 帮助我们把评审规则转化为可执行的工作流，并将关键评分准确率稳定在 75% 以上，显著提升了投标评审效率。” — 某大型能源国企项目负责人

“Agently 实现了从澄清到查询规划再到结果呈现的闭环流程，首次响应准确率达到 90% 以上，且生产环境表现稳定。” — 某大型能源集团数据负责人

“借助 Agently 的编排和会话能力，我们快速开发并上线了一款用于课程管理和答疑的教学助理系统，并持续迭代优化。” — 某大学教学助理项目负责人

您的项目也可以成为下一个成功案例。
📢 在 GitHub Discussions 分享您的案例 →

❓ 常见问题解答

问：Agently 与 LangChain 或 LlamaIndex 有何不同？
答： Agently 专为生产环境打造。它专注于稳定的接口（契约优先的输出）、易读易测的编排（TriggerFlow）以及可观察的工具调用（tool_logs）。对于那些在上线后需要可靠性和可维护性的团队来说，Agently 是更合适的选择。

问：支持哪些模型？切换模型的成本高吗？
答： 通过 OpenAICompatible，您可以连接 OpenAI、Claude、DeepSeek、Qwen 等大多数兼容 OpenAI 的 API，以及 Llama/Qwen 等本地模型。同一套业务代码无需修改即可切换模型，从而减少供应商锁定的风险。

问：学习曲线如何？我应该从哪里开始？
答： 核心 API 非常简单——您可以在几分钟内运行第一个代理。建议从 快速入门 开始，然后深入学习 输出控制 和 TriggerFlow。

问：如何部署基于 Agently 的服务？
答： Agently 不会限制您的部署方式。它提供了异步 API 和 FastAPI 示例。FastAPI 集成示例涵盖了 SSE、WebSocket 和标准 POST 请求。

问：是否提供企业级支持？
答： 是的。本仓库中的核心框架仍以 Apache 2.0 协议开源。企业级支持、私有扩展、托管服务以及基于 SLA 的合作，则通过单独的商业协议提供。您可以通过 社区 与我们联系。

问：Agently 的开源版与企业版有何区别？
答： 开源核心包括本仓库中的通用框架和公开功能。而企业版（例如私有扩展包、高级治理模块、私有部署支持以及 SLA 服务）则通过商业条款另行提供。

🧭 文档指南（核心路径）

• 入门
  • 快速上手：https://agently.tech/docs/en/quickstart.html
  • 模型设置：https://agently.tech/docs/en/model-settings.html
  • 官方 Agently 技能：https://github.com/AgentEra/Agently-Skills
• 输出控制（结构化输出）
  • 概述：https://agently.tech/docs/en/output-control/overview.html
  • 输出格式：https://agently.tech/docs/en/output-control/format.html
  • ensure_keys：https://agently.tech/docs/en/output-control/ensure-keys.html
  • 即时流式输出：https://agently.tech/docs/en/output-control/instant-streaming.html
• 结果与流式事件
  • 结果数据：https://agently.tech/docs/en/model-response/result-data.html
  • 流式事件：https://agently.tech/docs/en/model-response/streaming.html
• 会话与记忆
  • 概述：https://agently.tech/docs/en/agent-extensions/session-memo/
  • 快速上手：https://agently.tech/docs/en/agent-extensions/session-memo/quickstart.html
• TriggerFlow 编排
  • 概述：https://agently.tech/docs/en/triggerflow/overview.html
  • when 分支：https://agently.tech/docs/en/triggerflow/when-branch.html
  • if / elif / else：https://agently.tech/docs/en/triggerflow/if-branch.html
  • match / case：https://agently.tech/docs/en/triggerflow/match-branch.html
  • batch：https://agently.tech/docs/en/triggerflow/batch.html
  • for_each：https://agently.tech/docs/en/triggerflow/for-each.html
  • 运行时流：https://agently.tech/docs/en/triggerflow/runtime-stream.html
• 工具与扩展
  • 工具：https://agently.tech/docs/en/agent-extensions/tools.html
  • MCP：https://agently.tech/docs/en/agent-extensions/mcp.html
  • auto_func：https://agently.tech/docs/en/agent-extensions/auto-func.html
  • KeyWaiter：https://agently.tech/docs/en/agent-extensions/key-waiter.html
• 提示词管理：https://agently.tech/docs/en/prompt-management/overview.html
• 异步支持与配置：https://agently.tech/docs/en/async-support.html / https://agently.tech/docs/en/settings.html
• 工作手册：https://agently.tech/docs/en/agent-systems/overview.html

🤝 社区

• 讨论区：https://github.com/AgentEra/Agently/discussions
• 问题反馈：https://github.com/AgentEra/Agently/issues
• 微信群：https://doc.weixin.qq.com/forms/AIoA8gcHAFMAScAhgZQABIlW6tV3l7QQf

📄 许可证

Agently 采用开源核心 + 商业扩展的模式：

• 本仓库中的开源核心：Apache 2.0
• 商标使用政策：TRADEMARK.md
• 贡献者权利协议：CLA.md
• 企业级扩展及商业服务：通过单独的商业协议提供

---

开始构建您的生产就绪型 AI 应用 →
pip install -U agently

_{有疑问？请阅读 文档 或加入 社区。}

Agently 快速上手指南

Agently 是一个专为生产环境设计的 AI 应用开发框架，旨在通过契约优先的输出控制、可维护的工作流编排（TriggerFlow）和稳定的会话管理，解决大模型应用中的工程化难题。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：>= 3.10
• 推荐版本：Agently >= 4.0.7.2
• 前置依赖：无需额外系统级依赖，仅需标准的 Python 环境。

💡 国内开发者提示：建议使用国内镜像源加速安装过程（如清华源或阿里源）。

2. 安装步骤

基础安装

使用 pip 安装最新版本的 Agently：

pip install -U agently

国内加速安装（推荐）：

pip install -U agently -i https://pypi.tuna.tsinghua.edu.cn/simple

可选：安装官方技能包 (Agently Skills)

为了获得更好的路由实现、生产任务指引以及从 LangChain/LangGraph 迁移的支持，建议安装官方技能包：

npx skills add AgentEra/Agently-Skills

可选：安装开发工具 (DevTools)

如果需要运行时观察和开发者工具支持：

pip install agently-devtools

3. 基本使用

示例一：结构化输出 (Contract-first Output)

定义输出的数据结构，并强制关键字段存在，确保结果稳定可靠。

from agently import Agently

agent = Agently.create_agent()

result = (
    agent.input("用一句话介绍 Python 并列出 2 个优势")
    .output({
        "introduction": (str, "一句话介绍"),
        "advantages": [(str, "优势描述")]
    })
    .start(ensure_keys=["introduction", "advantages[*]"])
)

print(result)

示例二：工作流编排 (TriggerFlow)

使用 TriggerFlow 构建可读性强、支持分支判断的业务流程。

from agently import TriggerFlow, TriggerFlowEventData

flow = TriggerFlow()

@flow.chunk
def classify_intent(data: TriggerFlowEventData):
    text = data.value
    if "价格" in text:
        return "price_query"
    if "功能" in text:
        return "feature_query"
    return "other"

@flow.chunk
def handle_price(_: TriggerFlowEventData):
    return {"response": "价格取决于具体套餐..."}

@flow.chunk
def handle_feature(_: TriggerFlowEventData):
    return {"response": "我们的产品支持..."}

(
    flow.to(classify_intent)
    .match()
    .case("price_query")
    .to(handle_price)
    .case("feature_query")
    .to(handle_feature)
    .case_else()
    .to(lambda d: {"response": "您想了解什么？"})
    .end_match()
    .end()
)

print(flow.start("这个多少钱？"))

示例三：多轮会话管理 (Session)

激活会话以维持上下文，支持自定义记忆策略和持久化。

from agently import Agently

agent = Agently.create_agent()

# 激活用户会话
agent.activate_session(session_id="demo_user_1001")

# 设置上下文窗口最大长度
agent.set_settings("session.max_length", 12000)

# 后续对话将自动包含历史上下文
response = agent.input("继续刚才的话题").start()
print(response)