Skip to content

Latest commit

 

History

History
345 lines (264 loc) · 15.1 KB

README_CN.md

File metadata and controls

345 lines (264 loc) · 15.1 KB
image

Agently 4 🚀

让生产级 AI 应用开发更快、更稳、更可维护

English Introduction | 中文介绍

license PyPI version Downloads GitHub Stars Twitter Follow WeChat

🔥 最新文档与更新 | 🚀 5 分钟快速开始 | 💡 核心特性

📚 核心资源

🤔 为什么需要 Agently？

很多 GenAI POC 难以落地投产，问题往往不在模型“聪明与否”，而在工程可控性不足：

常见痛点 Agently 的解决方案
输出结构漂移、JSON 解析失败 契约式输出控制：output() + ensure_keys 保障关键字段稳定出现
工作流越来越复杂、难维护 TriggerFlow 编排：to / if / match / batch / for_each 让逻辑可读可测
多轮对话上下文不稳定 Session（v4.0.8.1+）：会话激活、上下文窗口控制、自定义 memo 策略与持久化
工具调用不可追踪 工具日志：extra.tool_logs 可审计、可复盘
切换/升级模型成本高 统一模型配置：OpenAICompatible 适配多家云端/本地模型

Agently 的核心价值是把 LLM 的不确定性转化为“稳定、可测试、可维护”的工程系统。

✨ 核心特性

1) 📝 契约式输出控制

用 output() 明确结构，用 ensure_keys 保障关键字段稳定出现，减少集成失败与返工。

result = (
    agent
    .input("分析用户反馈")
    .output({
        "情感倾向": (str, "积极/中立/消极"),
        "关键问题": [(str, "总结的问题点")],
        "紧急程度": (int, "1-5分")
    })
    .start(ensure_keys=["情感倾向", "关键问题[*]"])
)

2) ⚡ 结构化流式（Instant）

结构化字段边生成边可用，适合实时 UI 与动作触发。

response = (
    agent
    .input("解释递归，并给出 2 个提示")
    .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 工作流编排

支持 to、if/elif、match/case、batch、for_each，逻辑清晰可读、可测、可扩展。

(
    flow.to(接收请求)
    .if_condition(lambda d: d.value["type"] == "查询")
    .to(执行查询)
    .elif_condition(lambda d: d.value["type"] == "订购")
    .to(验证库存)
    .to(创建订单)
    .end_condition()
)

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

默认内置 SessionExtension，支持 activate_session/deactivate_session、上下文窗口控制、自定义 memo 策略与 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)

# 可选：自定义策略（analysis -> resize）
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) 🌐 统一模型配置（OpenAICompatible）

一套配置适配多家云端与本地模型，降低供应商锁定成本。

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):
    user_input = data.value
    if "价格" in user_input:
        return "price_query"
    if "功能" in user_input:
        return "feature_query"
    if "购买" in user_input:
        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 锁定必返字段。
⚡ 实时体验 UI 是否需要边生成边响应？ 消费 type="instant" 的结构化流式事件，实现实时更新。
🔍 可观测性 工具调用能否审计与复盘？ 查阅 extra.tool_logs，确保每次调用参数与结果可追溯。
🧩 流程健壮性 复杂工作流是否经过充分测试？ 对 TriggerFlow 的每个分支、并发上限进行单元测试，验证预期输出。
🧠 记忆与上下文 多轮对话体验是否一致可控？ 明确 Session/Memo 的摘要、裁剪与持久化策略。
📄 提示词管理 业务逻辑变更能否快速迭代？ 将 Prompt 配置化、版本化管理，实现变更可追踪。
🌐 模型策略 能否灵活切换或降级模型？ 通过 OpenAICompatible 集中配置，支持一键切换供应商。
🚀 性能与扩展 服务能否承受高并发？ 在真实 Web 服务场景下，验证全链路异步性能。
🧪 质量保障 回归测试是否完备？ 为每个核心场景编写固定输入与期望输出的测试用例。

📈 谁在用 Agently 解决真实问题？

"Agently 帮助我们将评标细则转为可执行流程，模型评分关键项准确率稳定在 75%+，评标效率显著提升。" — 某能源央企项目负责人

"Agently 让问数系统形成从澄清到查询到呈现的闭环，业务问题首次回复准确率达 90%+，上线后稳定运行。" — 某大型能源集团数据负责人

"Agently 的工作流编排与会话能力，让教学助手在课程管理与答疑场景快速落地，并保持持续迭代。" — 某高校教学助手项目负责人

你的项目也可以加入这个列表。
📢 来 GitHub Discussions 分享你的案例 →

❓ 常见问题

Q：Agently 和 LangChain、LlamaIndex 等框架的主要区别是什么？
A： 定位不同。Agently 专为生产环境设计，核心是解决“上线”后的工程问题：通过 契约式输出 保障接口稳定，通过 声明式编排（TriggerFlow） 实现复杂逻辑的可读可测，通过 全链路日志（如 tool_logs） 满足可观测性与审计需求。它更适合对交付稳定性、可维护性有较高要求的团队。

Q：具体支持哪些模型？切换成本高吗？
A： 通过标准的 OpenAICompatible 接口，可无缝接入 OpenAI、Claude、DeepSeek、通义千问等几乎所有主流云端模型，以及本地部署的 Llama、Qwen 等开源模型。一套业务代码，无需修改即可切换模型，大幅降低供应商锁定风险和迁移成本。

Q：框架的学习曲线如何？从哪里开始最好？
A： 基础 API 非常直观，5 分钟即可运行第一个智能体。建议从 快速开始 入手，然后根据需求深入查看 结构化输出、工作流编排 等核心章节。

Q：如何将基于 Agently 开发的服务部署上线？
A： 框架本身不绑定部署方式。它提供了完整的异步接口，可以轻松集成到 FastAPI、Django 等任何 Web 框架中。我们提供了开箱即用的 FastAPI 集成示例，涵盖 SSE（流式）、WebSocket 和普通 POST 接口。

Q：是否有企业版或商业支持？
A： 有。当前仓库中的 Agently 核心框架继续采用 Apache 2.0 开源协议。企业支持、私有扩展包、托管服务及 SLA 保障等能力通过独立商业协议提供。欢迎通过 社区 与我们联系。

Q：Agently 的开源能力和企业能力边界是什么？
A： 开源部分是本仓库中的通用框架能力；企业部分（例如私有扩展、治理模块、私有化部署支持与 SLA 服务）作为独立商业交付提供，不改变开源核心许可证。

🧭 文档库重要内容导览

🤝 加入社区

📄 开源协议

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

  • 本仓库开源核心： Apache 2.0
  • 商标使用规范： TRADEMARK.md
  • 贡献者授权协议： CLA.md
  • 企业扩展与商业服务：通过独立商业协议提供

立即开始构建你的生产级 AI 应用 →
pip install -U agently

有问题？查看 完整文档 或加入 社区交流