Semantic Kernel 引导式对话框架（Guided Conversations）完整指南：让 Agent 目标明确、节奏可控地主导对话

Semantic Kernel 引导式对话框架Guided Conversations完整指南让 Agent 目标明确、节奏可控地主导对话【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本文围绕 Semantic Kernel Python 仓库中的python/samples/demos/guided_conversations示例系统讲解引导式对话Guided Conversations这一 Agent 设计模式由带目标与约束的 Agent作为创造者主导一段与用户的多轮对话并在过程中持续生成表单、笔记、计划等产物artifact。读完本文你将掌握该框架的五大输入要素产物、规则、对话流程、上下文、资源约束、其用模型思考、用代码规划think with the model, plan with the code的核心设计原则以及如何基于 Semantic Kernel 的 Kernel/插件机制落地一套可靠的对话编排实现。什么是引导式对话Guided Conversations日常生活中大量对话场景都有一个共同特征一方带着明确目标和约束来主导对话另一方参与其中。例如老师引导学生完成一堂课呼叫中心坐席收集客户问题的信息销售代表帮助客户找到满足其需求的产品面试官通过一系列问题评估候选人与岗位的匹配度护士通过系列问题对患者症状的严重程度进行分诊会议中参与者轮流汇报进展并讨论下一步。这些场景的共同点是发生在创造者creator主导对话的一方与用户user(s)参与方之间。创造者定义目标、规划对话如何流动并通常在对话过程中通过一张表单收集关键信息ta 必须运用判断力让对话始终朝既定目标推进同时提前记录关键信息与规划。该示例的目标正是构建一个通用框架创建能够半自主地辅助创造者运行对话场景的 AI Agent并产出可用于追踪进度与结果的产物artifact例如笔记、表单和计划。该框架有一条关键准则think with the model, plan with the code用模型思考用代码规划——即模型负责理解用户输入并做出复杂决策而代码负责施加约束和提供结构从而使系统可靠reliable。对应到源码这段框架的核心实现在 guided_conversation_agent.py 中其GuidedConversation类聚合了会话记录、资源计数器、产物插件与议程插件并以 Semantic Kernel 的 Kernel 为执行底座见 guided_conversation_agent.py 的__init__。框架要解决的三大挑战作者团队在开发该示例时观察到用 Agent 做对话场景时的几个常见痛点并给出了对应的框架解法常见挑战Guided Conversations 的解法聚焦——Agent 容易偏离最初目标将 Agent 的目标定义为完成一个产物artifact即对话中 Agent 需要完成什么的精确表示节奏——对话推进过快、过于冗长、对时间缺乏感知鼓励 Agent 定期更新议程agenda每个议程项被分配估算的轮数时间限制由代码程序化校验并通过资源约束resource constraints将秒/分钟等时间单位程序化转换为轮数turns下游使用——聊天日志难以被进一步处理或分析产物artifact既是对话的结构化记录事后更易分析也是实时监控 Agent 进度的途径从源码看这三大挑战分别对应框架中的两个核心插件与一个工具类Artifact产物、Agenda议程与GCResource资源约束它们都被编排在GuidedConversation主类中见 guided_conversation_agent.py。安装与快速开始安装该示例复用 Semantic Kernel Python 源码的开发工具链——poetry其中semantic-kernel以 git 依赖方式指向仓库main分支的python子目录Python 版本要求为^3.10,3.13在python/samples/demos/guided_conversations目录下执行poetry install激活 poetry 创建的.venv虚拟环境为你要使用的 LLM 服务配置环境变量或准备一个.env文件如果你向pyproject.toml中添加了新依赖运行poetry update。快速开始Fork 本仓库按上文安装步骤安装依赖并配置环境变量先运行示例 Notebook01_guided_conversation_teaching.ipynb为了获得最佳质量与可靠性建议使用gpt-4-1106-preview或gpt-4o模型——该示例需要复杂的推理与函数调用function calling能力。交互式脚本 interactive_guided_conversation.py 中默认使用的部署即为gpt-4o-2024-05-13。Notebook 路线图notebooks/目录下共有 4 个 Notebook循序渐进地拆解框架01_guided_conversation_teaching.ipynb以一个小学教育场景为例演示完整的引导式对话流程Agent 引导 4 年级学生 David 完成一首藏头诗并在结束时输出反馈报告02_artifact.ipynb深入讲解产物插件03_agenda.ipynb深入讲解议程插件04_battle_of_the_agents.ipynbAgent 对战对比观察不同配置下的行为。五个输入要素定义一个引导式对话场景使用本框架定义新场景时需要提供以下输入其中后三个可选产物artifact必填一个 PydanticBaseModel类定义 Agent 需要在对话中完成的表单或工作记忆字段规则rules必填Agent 在对话中应遵循的该做/不该做dos and donts列表对话流程conversation flow可选用自然语言描述对话的步骤例如先讲解……再给出指令……然后让学生练习……。可选的原因是产物本身有时就可以充当对话流程当你想提供更多细节或难以用产物结构表达时使用该字段上下文context可选对话目标与 Agent 应知道的附加信息会被置于推理reasoning提示词的顶部资源约束resource constraint可选控制对话长度的约束包含两个要素单位unit度量长度的方式已实现seconds秒、minutes分钟、turns轮数未来可扩展如 token 成本等模式mode约束的施加方式已实现maximum上限Agent 可在资源耗尽前提前结束与exact精确Agent 应恰好用完给定资源。以上五个输入恰好对应GuidedConversation.__init__的签名见 guided_conversation_agent.pyartifact: BaseModel、rules: list[str]、conversation_flow: str | None、context: str | None、resource_constraint: ResourceConstraint | None。核心组件逐层拆解产物Artifact用 Pydantic 建模的目标即表单产物插件位于 artifact.py。它的核心设计是把 Agent 的目标定义为一个 Pydantic 模型并在整个对话中鲁棒地robustly更新模型字段。关键机制包括自动初始化为 Unanswered构造时会通过_modify_base_artifact生成一个新的模型类为所有字段设置默认值Unanswered见 artifact.py。因此提示词中Unanswered即代表该字段尚未完成。LLM 值字符串的解析LLM 返回的值永远是字符串例如[x, y]因此基类 base_model_llm.py 通过field_validator(*, modebefore)使用ast.literal_eval将字符串解析为正确类型同时保留纯字符串字段原样它还设置了validate_assignment True每次字段更新都触发校验与extra forbid禁止添加额外字段。带重试的更新循环核心接口update_artifact(field_name, field_value, conversation)会尝试更新字段如果 Pydantic 校验失败如日期格式不对会调用 LLM 决定二选一修复格式后重试更新或恢复对话向用户追问更多信息。重试次数由max_artifact_field_retries控制默认 2 次框架主类中固定为MAX_DECISION_RETRIES 2。失败的字段会被记录在failed_artifact_fields中并在更新超过重试上限后被跳过见 artifact.py。面向提示词的 Schema 清洗get_schema_for_prompt会把原始 JSON Schema 清洗为适合 LLM 阅读的形式去掉title/default把$ref替换为type附带自定义类型说明get_artifact_for_prompt会返回当前产物状态但完全省略已失败字段见 artifact.py。产物插件的另一个用法是作为 Agent 的工作记忆working memory在对话中持续记录关键信息。议程Agenda让节奏可被规划与校验议程插件位于 agenda.py。它管理一个由标题 所需轮数组成的议程项列表_BaseAgendaItemtitleresource见 agenda.py。更新与校验update_agenda(items, remaining_turns, conversation)接收 LLM 生成的议程项通过_validate_agenda_update进行程序化校验包括maximum模式下议程总轮数不得超过剩余轮数exact模式下议程总轮数必须恰好等于剩余轮数不要留下任何未分配的轮数任何一项的资源值都必须大于 0见 agenda.py。错误自愈校验失败时_fix_agenda_error调用 LLM 修正议程且系统提示词明确要求修正必须最小化改动不得改变第一项的描述因为已执行、不得合并掉已有主题见 agenda.py。重试上限由max_agenda_retries控制。提示词友好输出get_agenda_for_prompt将议程格式化为带编号、带累计轮数占比的文本便于放入推理提示词见 agenda.py。资源约束Resource Constraint把时间翻译成轮数资源约束定义在 resources.py单位ResourceConstraintUnitSECONDS、MINUTES、TURNS模式ResourceConstraintModeMAXIMUM上限与EXACT精确约束对象ResourceConstraintquantity数量unitmode三者组合。GCResource类负责跟踪资源消耗start_resource()在每轮对话开始时被调用对时间单位记录time.time()起点见 resources.pyincrement_resource()在每轮结束时按单位扣减资源并递增turn_number见 resources.pyestimate_remaining_turns()将秒/分钟单位折算为轮数基于initial_seconds_per_turn默认 120 秒/轮或已观测的平均每轮耗时估算剩余轮数见 resources.py。这里有一处重要的设计取舍议程校验始终以轮数为单位推理——作者团队发现 LLM 以轮数推理效果远好于以秒/分钟推理见 agenda.py 的注释因此即便你传入的是秒或分钟约束也会先被换算成轮数再参与议程规划。get_resource_instructions()还会根据EXACT/MAXIMUM模式生成细致的节奏指示如exact模式下最后一轮的特殊提示不要向用户暗示对话即将结束见 resources.py。若resource_constraint为None则对话可以无限持续且不会创建议程。编排器Orchestrator两步式计划-执行循环GuidedConversation主类guided_conversation_agent.py把以上组件组装成一个可交互的对话循环注册插件向 Kernel 注册四个工具——update_artifact_field更新产物字段、update_agenda更新议程、send_message_to_user给用户发消息、end_conversation结束对话并设置req_settings.max_tokens 2000见 guided_conversation_agent.py。两类插件plugins_order普通插件先执行更新产物 → 更新议程与terminal_plugins_order终结插件后执行且每轮只能执行一个发送消息 → 结束对话执行顺序即列表顺序见 guided_conversation_agent.py。单步循环step_conversation(user_input)这是对外的核心接口接收用户消息返回GCOutput(ai_message, is_conversation_over)。其内部是一个生成计划 → 执行计划的循环见 guided_conversation_agent.pygenerate_plan调用 conversation_plan.py 中的conversation_plan_function不调用任何工具仅要求模型逐步推理 给出推荐动作及全部所需参数。这一步是think with the model的体现先显式规划再产生工具调用已被证明能显著提升可靠性。推理内容还会以REASONING类型的消息加入会话记录供调试与复盘。execute_plan把计划文本作为输入通过 execution.py 中的execution模板调用FunctionChoiceBehavior.Auto(auto_invokeFalse, filters...)让模型基于计划生成真正的工具调用再经 openai_tool_calling.py 的parse_function_result与validate_tool_calling做工具名/参数的程序化校验ToolValidationResult枚举成功 / 未调用工具 / 调用了意外工具 / 缺少必填参数 / 参数类型错误并把调用按普通/终结两类排序。校验失败最多重试MAX_DECISION_RETRIES 2次若最终仍失败Agent 会回复错误消息并终止对话。终结收尾final_update当模型选择end_conversation时先调用 final_update_plan.py 的final_update_plan_function让模型基于完整对话历史最终更新一次产物例如纠正错误、回填遗漏字段甚至把错误信息重置为 Unanswered再正式结束对话见 guided_conversation_agent.py。可序列化to_json/from_json支持将产物、议程、聊天记录、资源状态整体导出与恢复便于持久化或断点续跑见 guided_conversation_agent.py。实战定义你自己的场景下面以交互脚本 interactive_guided_conversation.py 为模板完整演示如何定义一个新场景此处为教 4 年级学生写藏头诗。该脚本中五个输入的定义方式如下1) 产物任意合法 PydanticBaseModel均可from pydantic import BaseModel, Field class MyArtifact(BaseModel): student_poem: str Field(descriptionThe acrostic poem written by the student.) initial_feedback: str Field(descriptionFeedback on the students final revised poem.) final_feedback: str Field(descriptionFeedback on how the student was able to improve their poem.) inappropriate_behavior: list[str] Field( descriptionList any inappropriate behavior the student attempted while chatting with you. It is ok to leave this field Unanswered if there was none. )2) 规则dos and donts 列表rules [ DO NOT write the poem for the student., Terminate the conversation immediately if the student asks for harmful or inappropriate content., ]3) 对话流程可选自然语言描述步骤可包含具体示例conversation_flow 1. Start by explaining interactively what an acrostic poem is. 2. Then give the following instructions for how to go ahead and write one: ... 3. Then give the following example of a poem where the word or phrase is HAPPY: ... 4. Finally have the student write their own acrostic poem ... Have them revise their poem based on your feedback and then review it again.4) 上下文可选context You are working 1 on 1 with David, a 4th grade student, who is chatting with you in the computer lab at school while being supervised by their teacher.5) 资源约束可选例如设置精确 10 轮from guided_conversation.utils.resources import ( ResourceConstraint, ResourceConstraintMode, ResourceConstraintUnit, ) resource_constraint ResourceConstraint( quantity10, unitResourceConstraintUnit.TURNS, modeResourceConstraintMode.EXACT, )组装与运行用 Semantic Kernel 构建 Kernel此处以 Azure OpenAI 为例也可换成 OpenAI 服务然后实例化 Agent 并进入交互循环import asyncio from azure.identity import AzureCliCredential from semantic_kernel import Kernel from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion from guided_conversation.plugins.guided_conversation_agent import GuidedConversation async def main() - None: kernel Kernel() service_id gc_main chat_service AzureChatCompletion( service_idservice_id, deployment_namegpt-4o-2024-05-13, api_version2024-05-01-preview, credentialAzureCliCredential(), ) kernel.add_service(chat_service) guided_conversation_agent GuidedConversation( kernelkernel, artifactMyArtifact, conversation_flowconversation_flow, contextcontext, rulesrules, resource_constraintresource_constraint, service_idservice_id, ) # 与普通聊天机器人不同引导式对话 Agent 会主动发起第一句话 result await guided_conversation_agent.step_conversation() print(fAssistant: {result.ai_message}) while True: try: user_input input(User: ) except (KeyboardInterrupt, EOFError): print(\n\nExiting chat...) return if user_input exit: print(\n\nExiting chat...) return result await guided_conversation_agent.step_conversation(user_inputuser_input) print(fAssistant: {result.ai_message}) if result.is_conversation_over: return if __name__ __main__: asyncio.run(main())对话会在以下三种情况之一结束用户输入exit/ 中断Agent 主动结束对话资源约束耗尽、产物已完成、或用户不配合导致对话无法推进或出现系统错误。扩展与复用框架新增场景参考上文实战一节创建一个新文件并定义产物、规则、可选对话流程、可选上下文、可选资源约束即可也可直接修改 interactive_guided_conversation.py 中的对应变量来快速试玩。编辑现有插件插件的全部实现位于 guided_conversation/plugins/ 目录。编辑编排器编排逻辑集中在 guided_conversation_agent.py。复用插件项目欢迎社区直接抽取artifact与agenda两个插件用于既有工作——团队认为仅这两个插件本身就能提升其他 Agent 的目标遵循能力goal-following。设计要点与适用前提小结可靠性的来源是代码而非提示词产物字段校验由 Pydantic 强制执行议程轮数由_validate_agenda_update程序化校验工具调用由validate_tool_calling校验并支持最多 2 次重试LLM 只负责思考与生成参数这正是用模型思考、用代码规划的落地方式。模型要求框架依赖 function calling 与复杂推理README 明确建议使用gpt-4-1106-preview或gpt-4o以获得最佳质量与可靠性交互脚本默认使用gpt-4o-2024-05-13部署。环境前提本示例是 Semantic Kernel 仓库下的演示项目运行前需通过 poetry 安装依赖含 git 引用方式安装的semantic-kernel、配置 Azure OpenAI 或 OpenAI 凭据并满足 Python^3.10,3.13的版本要求。产物可作下游数据对话结束时final_update保证产物字段与对话内容一致产出的结构化 JSON可通过to_json()导出可直接用于生成报告、入库分析或作为后续流程的输入。如需进一步动手验证建议按顺序运行 01_guided_conversation_teaching.ipynb → 02_artifact.ipynb → 03_agenda.ipynb并在 04_battle_of_the_agents.ipynb 中对比不同配置下 Agent 的行为差异。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考