Agently框架：从零构建可工程化的大模型智能体应用-育师

1. 项目概述：从“智能体”到“智能体时代”的工程化跃迁

最近在跟几个做AI应用开发的朋友聊天，大家普遍有个感觉：大模型的能力是越来越强了，但真要把这些能力稳定、高效地集成到自己的业务系统里，总感觉像是在“手搓火箭”。今天想跟大家深入聊聊一个我最近在重度使用的框架——Agently（或者说，它所开启的AgentEra时代）。这不仅仅是一个工具库，更像是一套为“智能体”应用开发量身定制的工程化思想和最佳实践集合。

简单来说，Agently是一个面向大模型应用开发的框架，它的核心目标是把构建一个可靠、可维护、可扩展的AI智能体（Agent）的过程，从“写一次性脚本”变成“做标准化工程”。它提供了一套清晰的架构模式、丰富的内置组件和开箱即用的工具链，让开发者能像搭积木一样，快速组装出具备复杂推理、工具调用、记忆和规划能力的AI应用。无论你是想做一个能自动分析数据的智能助手，还是一个能处理多轮复杂对话的客服机器人，Agently都试图为你扫清工程上的障碍，让你更专注于业务逻辑和Prompt设计本身。

2. 核心设计哲学：为什么我们需要一个“框架”？

在深入代码之前，我们先得想明白一个问题：用大模型的API直接写几行调用代码就能出结果，为什么还需要一个框架？这恰恰是Agently要解决的核心痛点。

2.1 从“对话”到“工作流”的范式转变

早期的大模型应用，很多是“一问一答”式的。用户输入一个问题，模型返回一段文本。但随着应用深入，需求变得复杂：一次任务可能需要模型进行多步思考（Chain-of-Thought）、调用外部工具（如查询数据库、执行代码）、记住之前的对话历史，甚至根据中间结果动态调整后续步骤。这种复杂的、有状态的、多步骤的交互过程，我称之为“工作流”。

如果全靠开发者手动用代码去拼接API调用、管理状态、处理错误，代码会迅速变得臃肿且难以维护。Agently的哲学，就是将这种“工作流”抽象为一等公民。它定义了清晰的执行阶段（如计划、执行、观察、反思），并提供了相应的钩子和生命周期管理，让开发者可以声明式地描述智能体的行为，而不是命令式地操控每一个细节。

2.2 关注点分离：让Prompt工程师和软件工程师各司其职

在一个成熟的AI应用团队里，往往有两种角色：擅长设计提示词、挖掘模型潜力的“Prompt工程师”，和擅长构建稳定后端服务、设计数据流的“软件工程师”。传统的开发方式容易让两者的工作纠缠在一起——Prompt里混着逻辑判断，业务代码里散落着各种格式化的字符串。

Agently通过清晰的架构，促进了关注点分离。它允许你将智能体的能力定义（Skill）、推理逻辑（通过Prompt模板）、工具（Tool）以及执行引擎分离开来。Prompt工程师可以专注于打磨.yaml或.jinja2格式的模板文件，定义模型的思考过程；而软件工程师则可以专注于工具的实现、状态管理、性能优化和系统集成。两者通过框架定义的接口进行协作，大大提升了开发效率和代码的可读性。

2.3 可观测性与可调试性成为刚需

当你的智能体在线上处理真实用户请求时，如果它给出了一个匪夷所思的回答，你该如何排查？是因为Prompt没写对？工具调用失败了？还是上下文记忆出现了偏差？没有框架的裸奔开发，调试就像在黑箱里摸象。

Agently内置了强大的可观测性支持。它可以详细记录一次智能体执行的完整生命周期日志，包括：接收到的输入、每一步的计划（Plan）、调用的工具及其参数、工具返回的结果、模型的中间思考过程（如果设置了输出思考链）、以及最终的回答。这些结构化的日志，对于复盘问题、优化Prompt、分析智能体行为模式至关重要。框架化使得为整个执行过程添加统一的监控、埋点和审计变得异常简单。

3. Agently框架核心架构深度解析

理解了“为什么”，我们再拆解“是什么”。Agently的架构可以概括为“一个核心，四大支柱”。

3.1 核心运行时：Agent Instance

智能体实例（Agent）是框架的核心运行时对象。它不是一个简单的模型调用封装，而是一个拥有状态、身份和能力的“虚拟个体”。创建一个智能体时，你可以为其设定：

身份（Role）：例如“资深数据分析师”、“幽默的英语陪练”。这个身份会通过System Prompt注入，持续影响模型的言行风格。
模型配置：支持多种后端模型（OpenAI GPT系列、 Anthropic Claude、国内主流平台模型等），并可配置温度、最大token等参数。
记忆系统：短期会话记忆（Conversation Memory）和可扩展的长期记忆（如向量数据库存储）。
技能与工具集：该智能体被授权可以使用的所有能力。

# 一个简单的Agently智能体创建示例（概念性代码） from agently import Agent # 创建一个数据分析师智能体 data_agent = Agent( role="你是一名严谨的数据分析师，擅长从数据中发现问题并给出商业建议。", model="gpt-4", # 指定模型后端 temperature=0.2, # 较低的温度，输出更确定 ) # 后续可以为这个agent装配特定的工具和技能

3.2 支柱一：技能（Skill）抽象层

Skill是Agently对智能体可复用能力的封装。一个Skill通常对应一个具体的任务，比如“生成SQL查询”、“总结长文本”、“进行多轮追问澄清需求”。Skill的内部包含了：

Prompt模板：定义如何让模型理解这个任务并进行思考。模板中可以使用变量插值。
输出解析器：定义如何将模型返回的非结构化文本，解析成结构化的数据（如JSON、Python字典），方便后续程序处理。
可能的前置/后置处理逻辑。

通过Skill，开发者可以将经过精心调试的Prompt工程成果沉淀为团队资产，新项目直接引入即可，避免了重复劳动和“Prompt魔法字符串”满天飞的情况。

3.3 支柱二：工具（Tool）调用与集成框架

工具调用（Function Calling）是让智能体从“聊天”走向“实干”的关键。Agently对工具调用做了极佳的抽象和简化：

声明式定义：使用装饰器或YAML文件，以极简的方式声明一个Python函数可以作为工具被AI调用，包括函数描述、参数描述（类型、含义）。
自动编排：框架负责将工具的声明信息格式化成模型能理解的Schema，并在模型请求调用时，自动匹配、执行对应的Python函数，并将结果返回给模型进行后续推理。
安全管控：可以精细控制每个智能体实例所能访问的工具范围，实现权限隔离。

from agently import tool # 使用装饰器声明一个工具 @tool def get_current_weather(city: str, unit: str = "celsius") -> str: """ 获取指定城市的当前天气情况。 Args: city: 城市名称，例如“北京”、“上海”。 unit: 温度单位，“celsius” 或 “fahrenheit”。 """ # 这里实现实际的天气API调用 # ... return f"{city}的天气是晴，温度25{unit}。" # 创建智能体并装配工具 agent = Agent() agent.use_tools([get_current_weather]) # 将工具装配给智能体 # 现在，当用户问“北京天气怎么样？”时，智能体会自动调用这个工具。

3.4 支柱三：工作流（Workflow）与规划（Planning）

对于复杂任务，智能体需要自己制定计划。Agently提供了两种主要的范式：

线性链（Chain）：最简单的A->B->C式顺序执行。适合步骤固定、流程明确的任务。
基于LLM的规划器（Planner）：让模型自己根据目标，动态生成一个步骤列表（Plan），然后逐步执行。这赋予了智能体更强的自主性和应对不确定性的能力。

框架的“执行引擎”会驱动智能体按照计划一步步前进，在每个步骤中决定是进行内部推理，还是调用外部工具，并根据执行结果决定是继续、重试还是调整计划。这个过程完全由框架托管，开发者只需定义好可用的Skill和Tool。

3.5 支柱四：记忆（Memory）管理系统

没有记忆的对话是苍白无力的。Agently的记忆系统分为多层：

会话记忆：自动维护当前对话的上下文。它不仅仅是保存历史消息，更重要的是会进行智能摘要和压缩，以防止上下文窗口爆炸。
长期记忆：可以通过插件集成向量数据库（如Chroma, Weaviate），让智能体拥有“知识库”，实现基于过去经验或私有知识的学习和回忆。
状态记忆：在Workflow执行过程中，维护任务相关的中间状态变量。

记忆系统的存在，使得构建能进行深度、连续协作的智能体成为可能。

4. 实战：从零构建一个数据分析智能体

理论说得再多，不如动手做一遍。我们一起来构建一个相对完整的“数据分析智能体”，它能接受用户用自然语言描述的数据分析需求，自动进行数据查询、处理和可视化。

4.1 第一步：定义智能体角色与核心技能

首先，我们明确这个智能体的“人设”：它是一名乐于助人且细致的数据分析师，拥有数据查询、清洗、分析和可视化的全套技能。

我们为它创建两个核心Skill：

需求澄清技能：当用户需求模糊时，主动进行多轮提问，明确分析目标、数据维度、时间范围等。
SQL生成与执行技能：将明确的分析需求，转化为针对特定数据库的SQL查询。

# skill_clarify.yaml (Skill定义示例) name: clarify_analysis_request description: 通过与用户对话，澄清模糊的数据分析需求。 prompt_template: | 用户提出了一个数据分析请求：{{user_request}} 这个请求可能比较模糊。你的目标是提出最多3个关键问题，帮助明确以下信息： 1. 分析的核心目标是什么？（例如：是趋势分析、异常检测、对比分析还是构成分析？） 2. 需要关注哪些核心数据维度或指标？ 3. 是否有明确的时间范围或数据筛选条件？ 请以友好、专业的方式提出问题。 output_parser: type: json schema: questions: list[str] # 解析出提出的问题列表

4.2 第二步：实现并封装数据工具

智能体需要操作真实数据，我们必须为其提供安全的工具。这里我们创建三个工具：

query_database(sql): 执行SQL并返回结果（DataFrame格式或JSON）。
generate_chart(data, chart_type, title): 使用Matplotlib或Plotly生成图表，返回图片文件路径或Base64编码。
summarize_findings(analysis_result): 对数据分析结果进行文本总结。

关键注意事项：工具的安全性与错误处理在实现query_database时，绝不能直接拼接用户输入生成SQL。我们的策略是：

在Skill的Prompt中，严格要求模型输出的SQL必须是“只读”的SELECT语句。
在工具函数内部，添加SQL语法校验（例如使用sqlparse库），拒绝包含INSERT,UPDATE,DELETE,DROP等危险关键词的语句。
设置查询超时和返回行数限制，防止复杂查询拖垮数据库。

# tools/data_tools.py import pandas as pd import sqlparse from typing import List, Dict, Any @tool def query_database(sql_query: str, limit: int = 1000) -> Dict[str, Any]: """ 在安全限制下执行只读的SQL查询，返回数据。 严格禁止执行任何数据修改（INSERT/UPDATE/DELETE）或结构修改（DROP/ALTER）语句。 Args: sql_query: 合法的SELECT查询语句。 limit: 返回结果的最大行数，防止数据过量。 Returns: 包含查询状态和数据的字典。例如：{'success': True, 'data': [...], 'columns': [...]} """ # 1. 安全检查 parsed = sqlparse.parse(sql_query)[0] if not parsed.is_readonly(): return {'success': False, 'error': '只允许执行SELECT查询语句。'} # 2. 添加LIMIT子句（如果原SQL没有） # ... (实现略) # 3. 执行查询（使用你的数据库连接，如SQLAlchemy） try: # engine = get_database_engine() # df = pd.read_sql_query(final_sql, engine) df = pd.DataFrame() # 示例 return { 'success': True, 'data': df.head(limit).to_dict('records'), 'columns': list(df.columns), 'row_count': len(df) } except Exception as e: return {'success': False, 'error': f'数据库查询失败：{str(e)}'}

4.3 第三步：组装智能体并设计工作流

现在，我们将角色、技能和工具组装起来，并设计一个简单的工作流。

# main.py from agently import Agent, Workflow from skills import clarify_skill, analysis_skill # 假设已导入定义好的Skill from tools.data_tools import query_database, generate_chart, summarize_findings # 1. 创建智能体实例 data_analyst = Agent( name="DataInsight", role="你是一名专业的数据分析师，擅长将业务问题转化为数据查询，并通过图表和文字提供清晰洞察。你思维严谨，注重数据准确性。", model="gpt-4", ) # 2. 装配工具 data_analyst.use_tools([query_database, generate_chart, summarize_findings]) # 3. 装配技能 data_analyst.use_skills([clarify_skill, analysis_skill]) # 4. 定义一个简单的工作流 def analysis_workflow(user_query: str): """数据分析智能体的核心工作流""" agent = data_analyst.new_session() # 为新会话创建一个实例 # 步骤1：需求澄清 clarification = agent.skills.clarify_analysis_request(user_request=user_query) if clarification['questions']: # 如果有需要澄清的问题，先与用户交互（这里简化为打印） print("智能体需要澄清：", clarification['questions']) # 在实际应用中，这里应收集用户的进一步输入 # clarified_input = get_user_feedback(clarification['questions']) # user_query = clarified_input # 更新查询 # 步骤2：生成并执行分析 # 这里，analysis_skill会引导模型制定计划：生成SQL -> 调用工具查询 -> 分析结果 -> 生成图表 -> 撰写总结 final_result = agent.skills.perform_data_analysis(analysis_goal=user_query) return final_result # 5. 运行工作流 if __name__ == "__main__": result = analysis_workflow("帮我分析一下上个季度各产品的销售额趋势和占比情况。") print(result)

4.4 第四步：加入记忆与多轮对话能力

为了让智能体在同一个会话中记住之前的上下文，我们需要启用并配置记忆。

from agently import Memory # 创建带有记忆能力的智能体 data_analyst_with_memory = Agent( role="...", model="...", memory=Memory( type="session", # 会话记忆 max_turns=20, # 保留最近20轮对话 summarization=True # 启用自动摘要，当对话轮次过多时，将早期对话总结成要点，节省token ) ) # 现在，智能体会自动将每轮对话的输入输出存入记忆。 # 在后续对话中，例如用户说“对比一下这个数据和之前提到的数据”，智能体就能从记忆中找到“之前提到的数据”。

5. 开发中的常见“坑”与优化技巧

在实际使用Agently开发项目的过程中，我踩过不少坑，也总结了一些能大幅提升体验和效果的技巧。

5.1 提示词工程：从“魔法”到“工程”

坑点1：Prompt过于冗长或模糊，导致模型行为不稳定。技巧：遵循“清晰指令、提供示例、分步思考”的原则。Agently的Skill模板非常适合做这件事。将复杂的任务拆解成多个Skill，每个Skill的Prompt只关注一个子任务。大量使用少样本示例（Few-Shot Examples）在Prompt中，这是稳定模型输出的最有效方法之一。

坑点2：工具描述不清，导致模型不会用或用错。技巧：@tool装饰器中的函数文档字符串（Docstring）就是模型的“工具说明书”。务必详细、准确地描述工具的功能、每个参数的含义、格式和示例。例如，city参数写明“请输入完整的城市中文名，如‘北京市’，‘上海市黄浦区’”。

5.2 性能与成本优化

坑点3：上下文token无节制增长，导致API调用慢且贵。技巧：

务必开启记忆摘要功能：这是控制成本的生命线。
精简System Prompt：只保留最核心的身份和规则描述，移除冗余的客气话。
结构化输出：要求模型输出JSON等结构化格式，而非冗长的自然语言，后续解析既准确又省token。
流式处理：对于长文本生成，使用流式响应（Streaming）提升用户体验。

坑点4：工具调用失败导致整个流程中断。技巧：在工具函数内部做好全面的错误捕获和友好返回。不要抛出Python异常，而是返回一个结构化的错误信息，例如{'success': False, 'error': '原因'}。在Skill的Prompt中，可以指导模型：“如果工具调用失败，请根据错误信息尝试调整参数或换一种方式，并向用户说明情况。”

5.3 可观测性与调试

坑点5：智能体给出了错误答案，但不知道是哪个环节出了问题。技巧：充分利用Agently的日志记录。将Agent的日志级别设置为DEBUG，这样你可以看到完整的思考链、工具调用请求和响应。我通常会把这些日志结构化地输出到文件或监控系统（如ELK），便于事后分析。对于复杂Workflow，可以在关键步骤后插入“检查点”，输出中间状态，方便定位问题。

5.4 安全与合规

坑点6：智能体被用户诱导执行危险操作或泄露敏感信息。技巧：

工具层面的白名单机制：严格限制每个智能体可访问的工具范围。数据分析智能体绝不应该有“发送邮件”或“删除文件”的工具。
输入输出过滤与审核：在智能体与用户交互的边界层，添加内容过滤模块，对敏感词、个人身份信息（PII）进行检测和脱敏。
权限上下文传递：如果智能体需要代表用户操作其他系统，应将用户的权限令牌（Token）或角色信息作为会话上下文的一部分传递给工具函数，由工具函数在底层进行权限校验。

6. 进阶模式：构建具有“协作”与“反思”能力的智能体系统

当单个智能体能力有限时，我们可以让多个智能体协作，甚至让智能体具备“反思”能力，实现自我改进。

6.1 多智能体协作模式

想象一个产品需求评审场景：我们可以创建三个智能体：

产品经理智能体：负责阐述需求背景和目标。
工程师智能体：负责评估技术可行性和工作量。
设计师智能体：负责讨论用户体验和交互细节。

使用Agently，可以创建一个“协调员”智能体（Orchestrator），它的工作是主持这场会议：依次邀请各方发言，总结共识，指出分歧，并推动形成结论。每个专业智能体都配备其专属的技能和工具（如工程师能调用代码库分析工具）。这种模式能将复杂问题的多维度分析自动化。

6.2 让智能体学会“反思”

一个更高级的模式是让智能体在任务结束后进行自我反思。我们可以创建一个review_skill，在Workflow的最后一步被调用。这个Skill的Prompt是：“请回顾你刚才完成的整个任务过程。1. 最终结果是否完全满足了用户的需求？2. 在推理或执行过程中，有没有可以优化的步骤？3. 如果让你重做一次，你会怎么做？” 智能体的反思结果可以被存储到它的长期记忆中，当下次遇到类似任务时，这些经验就能被调用出来，从而实现持续的性能进化。

7. 总结与展望：AgentEra下的开发范式

使用Agently这类框架进行开发，给我的最大感触是思维模式的转变。我们不再是在“调用一个API”，而是在“设计并培育一个数字员工”。你需要考虑它的身份、技能、工具、工作流程，以及如何让它从经验中学习。

这个过程仍然充满挑战，尤其是在复杂逻辑的可靠性、长程任务的规划稳定性、以及与现实世界系统集成的安全性方面。但Agently提供了一个坚实、清晰的工程基础，让开发者能站在更高的抽象层次上去应对这些挑战，而不是陷入胶水代码的泥潭。

从我个人的实践来看，拥抱AgentEra，意味着要将软件工程中那些久经考验的思想——模块化、接口设计、测试驱动、可观测性——重新应用到AI应用开发中来。Agently正是这样一座桥梁。如果你正准备将大模型能力深度集成到你的产品中，花时间深入学习和实践这样一个框架，绝对是值得的。它不能解决所有问题，但它能为你提供一套解决问题的强大工具箱和思维框架。