OGX 实验性 Agents API 深度解析基于 Session 与 Turn 的 Agent 编程模型【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx本文以 docs/supplementary/experimental/agents-api.md 为骨架结合 OGX 仓库中的构建指南、API 概览与集成测试系统讲解实验性 Agents API 的核心概念、工具与安全配置、Memory 集成方式及其与稳定版 Responses API 的关系。读完本文你将掌握 Agents API 的 Agent / Session / Turn 三层抽象、如何为 Agent 装配工具与护栏以及如何在 OGX 中运行多步 Agent 工作流。一、Agents API 是什么实验性状态与定位OGXOpen GenAI Stack提供了一套实验性Experimental的Agents API用于构建具备工具调用、记忆RAG与复杂推理能力的多步 Agent 工作流。根据 docs/supplementary/experimental/agents-api.md 的说明 EXPERIMENTAL该 API 处于预览阶段可能根据用户反馈而变化。非常适合探索新能力并为最终设计提供反馈。这意味着它是 OGX 面向新能力探索的试验田功能可用但 API 形态尚未冻结。在 docs/docs/api/index.mdx 的 API 清单中Agents API 被描述为Run multi-step agentic workflows with LLMs, including tool usage, memory (RAG), and complex reasoning.即用 LLM 运行多步 agentic 工作流包含工具使用、记忆RAG与复杂推理。1.1 与稳定版 Responses API 的关系OGX 目前同时存在两条面向 Agent 应用的 API 路径。在 docs/docs/building_applications/responses_vs_agents.mdx 中明确指出Responses API是 OpenAI 兼容的稳定接口支持每次调用动态切换模型、工具、向量库并通过previous_response_id实现对话分支branching推荐用于新项目Agents API是更早的、OGX 特有的接口采用会话 回合Session Turn模型仍可正常运行但不推荐新项目使用。同时docs/supplementary/deprecated/agents-api.md 提供了从旧版 Agent 接口迁移到稳定版 Responses API 的指引说明仓库对老用户的迁移路径是清晰的。本文聚焦于实验性 Agents API 本身的能力与设计。二、核心概念Agent、Session 与 TurnAgents API 的主干是三个层层递进的抽象来自 docs/supplementary/experimental/agents-api.md 的核心功能列表创建 Agent以特定指令instructions配置 Agent并赋予其使用工具的能力Session会话与 Agent 的交互被分组为会话threads线程承载一段对话的连续状态Turn回合会话中的每次交互被称为一个 turn即用户输入 → Agent 内部处理 → 输出的完整过程。2.1 AgentConfig模型的人格与工具箱在 docs/docs/building_applications/agent.mdx 中Agent 通过AgentConfig类配置包含四个核心维度Model驱动 Agent 的底层 LLMInstructions定义 Agent 行为的系统提示词system promptToolsAgent 可用于与外部系统交互的能力集合Guardrails可选的、经由 Responses provider 执行的审核检查。仓库给出了最简创建示例from ogx_client import Agent # Create the agent agent Agent( ogx_client, modelmeta-llama/Llama-3-70b-chat, instructionsYou are a helpful assistant that can use tools to answer questions., tools[builtin::code_interpreter, builtin::file_search], )从源码结构看src/ogx/providers/remote/agents/__init__.py是远程 Agent provider 的聚合入口说明 Agent 的执行既可以是单机内置Builtin实现也可以通过远程 provider 承载。2.2 Session对话线程的载体Session 相当于传统聊天界面中的会话线程用于在多次交互之间保持 Agent 的连续状态# Create a session session_id agent.create_session(session_nameMy conversation)会话抽象的价值在于同一 Agent 可以并行服务于多个会话彼此状态隔离而单会话内的多轮交互则共享上下文。2.3 Turn一次完整交互的生命周期每次与 Agent 的交互都是一个 turn由三部分组成docs/docs/building_applications/agent.mdxInput Messages用户发送给 Agent 的内容StepsAgent 的内部处理过程推理、工具执行等Output MessageAgent 的最终回复。Turn 支持流式与非流式两种调用方式。流式版本配合AgentEventLogger可逐步打印事件from ogx_client import AgentEventLogger # Create a turn with streaming response turn_response agent.create_turn( session_idsession_id, messages[{role: user, content: Tell me about Llama models}], ) for log in AgentEventLogger().log(turn_response): log.print()非流式版本则一次性返回完整结构便于程序化处理from rich.pretty import pprint # Non-streaming API response agent.create_turn( session_idsession_id, messages[{role: user, content: Tell me about Llama models}], streamFalse, ) print(Inputs:) pprint(response.input_messages) print(Output:) pprint(response.output_message.content) print(Steps:) pprint(response.steps)2.4 Steps可观测的 Agent 内部过程Turn 之所以可观测是因为它把 Agent 的思考过程拆解为一个个Step主要包括三类docs/docs/building_applications/agent.mdxInference StepsAgent 生成文本回复的推理过程Tool Execution StepsAgent 调用工具获取信息的执行过程Guardrails Steps审核moderation检查的执行过程。这为调试、日志记录和成本分析提供了细粒度的钩子更深层的执行流程可参阅 agent_execution_loop.mdx。三、工具系统ToolGroups 与 ToolRuntimeAgents API 的原始文档明确指出Agents can be provided with various tools (see the ToolGroups and ToolRuntime APIs for more details). 即 Agent 的工具能力来自 OGX 的两套底层 APIToolGroups对工具进行分组管理的 API将相关工具组织成组便于按需装配ToolRuntime工具运行时 API负责工具的实际执行与生命周期。在上面的示例中tools[builtin::code_interpreter, builtin::file_search]即采用builtin::前缀的内置工具组无需额外配置即可使用。OGX 同时支持通过Connectors APIv1beta注册 MCP 等外部工具服务器实现工具生态的扩展见 docs/docs/api-experimental/index.mdx。更完整的工具集成方式可参考 tools.mdx。四、安全护栏Moderation 与 Guardrails根据 docs/supplementary/experimental/agents-api.mdAgents can be configured with moderation and guardrail settings through model and endpoint configuration.即 Agent 的审核与护栏不是通过 Agent 对象自身配置而是通过底层的模型model与端点endpoint配置注入的。这条设计意味着护栏能力复用自 Responses provider 的 guardrails 机制团队可以在网关/端点层面统一管控审核策略而不必在每个 Agent 中重复配置。对照 docs/docs/building_applications/responses_vs_agents.mdx 中的对比表Responses API 通过请求参数guardrailstrue配合已配置的moderation_endpoint启用护栏Agents API 则经由底层 Responses provider 的 guardrails 间接生效。因此在实验性 Agents API 上启用审核实际是在其底层模型/端点配置中设定 moderation 参数。五、记忆与知识库RAG Tool 与 Vector IO实验性 Agents API 的另一项核心能力是记忆Agents can also use Memory to retrieve information from knowledge bases. See the RAG Tool and Vector IO APIs for more details.这里的 Memory 指的不是模型上下文窗口而是从外部知识库检索信息的能力落地依赖两套 APIRAG Tool把检索增强生成封装为 Agent 可调用的工具在src/ogx_api/rag_tool.py中有对应实现Vector IO API对向量库执行添加文档、搜索、删除等操作见 vector_io 系列文档。工作流大致为文档先经 Vector IO 写入向量库Agent 在回合中通过 RAG Tool 检索相关片段再交给 LLM 组织回答。这正是 docs/docs/building_applications/rag.mdx 所描述的知识增强型 Agent路径。仓库还提供了完整的 RAG 基准评测框架见 benchmarking/rag 目录及其配套博客 2026-05-26-rag-benchmarks.md。六、支持的 Provider 与运行形态根据 docs/docs/api/index.mdxAgents API 的受支持 Provider 为Builtin单节点内置实现适合本地开发与轻量部署Fireworks托管云端托管推理Together托管云端托管推理PyTorch ExecuTorch设备端 iOS面向移动端的设备上推理。其中 Builtin 与远程 provider 的执行代码分别位于 src/ogx/providers/inline 与 src/ogx/providers/remote/agents/init.py可据此了解不同形态下的接入差异。仓库的集成测试 tests/integration/agents/test_openai_responses.py 则验证了 Agent 场景与 OpenAI Responses 协议互通的行为。七、实验性 API 的使用注意事项由于该 API 处于预览阶段使用时应关注以下约束接口可能变更OGX 的 Experimental APIs 说明 明确警告实验性 API 可能在 minor 版本中引入破坏性变更若稳定性敏感请锁定客户端版本适合探索与反馈官方欢迎就 API 设计与可用性、性能特征、缺失功能、集成模式四个方面提供反馈渠道见关联文档新项目优先选择稳定接口对于生产应用建议使用具备向后兼容保证的 Responses API它支持标准 OpenAI SDK、动态配置与对话分支。八、小结实验性 Agents API 为 OGX 提供了以Agent指令 工具→ Session会话线程→ Turn交互回合→ Steps可观测过程为骨架的 Agent 编程模型并串联了 ToolGroups/ToolRuntime 工具系统、基于 model/endpoint 配置的 moderation 护栏、以及基于 RAG Tool 与 Vector IO 的知识库记忆。虽然它正逐步让位于更稳定的 Responses API但其抽象设计——尤其是会话内多轮状态 回合级可观测性——依然是理解 OGX Agent 生态的重要入口也为评估与反馈下一代 Agent 接口提供了实验场地。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OGX 实验性 Agents API 深度解析：基于 Session 与 Turn 的 Agent 编程模型
OGX 实验性 Agents API 深度解析基于 Session 与 Turn 的 Agent 编程模型【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx本文以 docs/supplementary/experimental/agents-api.md 为骨架结合 OGX 仓库中的构建指南、API 概览与集成测试系统讲解实验性 Agents API 的核心概念、工具与安全配置、Memory 集成方式及其与稳定版 Responses API 的关系。读完本文你将掌握 Agents API 的 Agent / Session / Turn 三层抽象、如何为 Agent 装配工具与护栏以及如何在 OGX 中运行多步 Agent 工作流。一、Agents API 是什么实验性状态与定位OGXOpen GenAI Stack提供了一套实验性Experimental的Agents API用于构建具备工具调用、记忆RAG与复杂推理能力的多步 Agent 工作流。根据 docs/supplementary/experimental/agents-api.md 的说明 EXPERIMENTAL该 API 处于预览阶段可能根据用户反馈而变化。非常适合探索新能力并为最终设计提供反馈。这意味着它是 OGX 面向新能力探索的试验田功能可用但 API 形态尚未冻结。在 docs/docs/api/index.mdx 的 API 清单中Agents API 被描述为Run multi-step agentic workflows with LLMs, including tool usage, memory (RAG), and complex reasoning.即用 LLM 运行多步 agentic 工作流包含工具使用、记忆RAG与复杂推理。1.1 与稳定版 Responses API 的关系OGX 目前同时存在两条面向 Agent 应用的 API 路径。在 docs/docs/building_applications/responses_vs_agents.mdx 中明确指出Responses API是 OpenAI 兼容的稳定接口支持每次调用动态切换模型、工具、向量库并通过previous_response_id实现对话分支branching推荐用于新项目Agents API是更早的、OGX 特有的接口采用会话 回合Session Turn模型仍可正常运行但不推荐新项目使用。同时docs/supplementary/deprecated/agents-api.md 提供了从旧版 Agent 接口迁移到稳定版 Responses API 的指引说明仓库对老用户的迁移路径是清晰的。本文聚焦于实验性 Agents API 本身的能力与设计。二、核心概念Agent、Session 与 TurnAgents API 的主干是三个层层递进的抽象来自 docs/supplementary/experimental/agents-api.md 的核心功能列表创建 Agent以特定指令instructions配置 Agent并赋予其使用工具的能力Session会话与 Agent 的交互被分组为会话threads线程承载一段对话的连续状态Turn回合会话中的每次交互被称为一个 turn即用户输入 → Agent 内部处理 → 输出的完整过程。2.1 AgentConfig模型的人格与工具箱在 docs/docs/building_applications/agent.mdx 中Agent 通过AgentConfig类配置包含四个核心维度Model驱动 Agent 的底层 LLMInstructions定义 Agent 行为的系统提示词system promptToolsAgent 可用于与外部系统交互的能力集合Guardrails可选的、经由 Responses provider 执行的审核检查。仓库给出了最简创建示例from ogx_client import Agent # Create the agent agent Agent( ogx_client, modelmeta-llama/Llama-3-70b-chat, instructionsYou are a helpful assistant that can use tools to answer questions., tools[builtin::code_interpreter, builtin::file_search], )从源码结构看src/ogx/providers/remote/agents/__init__.py是远程 Agent provider 的聚合入口说明 Agent 的执行既可以是单机内置Builtin实现也可以通过远程 provider 承载。2.2 Session对话线程的载体Session 相当于传统聊天界面中的会话线程用于在多次交互之间保持 Agent 的连续状态# Create a session session_id agent.create_session(session_nameMy conversation)会话抽象的价值在于同一 Agent 可以并行服务于多个会话彼此状态隔离而单会话内的多轮交互则共享上下文。2.3 Turn一次完整交互的生命周期每次与 Agent 的交互都是一个 turn由三部分组成docs/docs/building_applications/agent.mdxInput Messages用户发送给 Agent 的内容StepsAgent 的内部处理过程推理、工具执行等Output MessageAgent 的最终回复。Turn 支持流式与非流式两种调用方式。流式版本配合AgentEventLogger可逐步打印事件from ogx_client import AgentEventLogger # Create a turn with streaming response turn_response agent.create_turn( session_idsession_id, messages[{role: user, content: Tell me about Llama models}], ) for log in AgentEventLogger().log(turn_response): log.print()非流式版本则一次性返回完整结构便于程序化处理from rich.pretty import pprint # Non-streaming API response agent.create_turn( session_idsession_id, messages[{role: user, content: Tell me about Llama models}], streamFalse, ) print(Inputs:) pprint(response.input_messages) print(Output:) pprint(response.output_message.content) print(Steps:) pprint(response.steps)2.4 Steps可观测的 Agent 内部过程Turn 之所以可观测是因为它把 Agent 的思考过程拆解为一个个Step主要包括三类docs/docs/building_applications/agent.mdxInference StepsAgent 生成文本回复的推理过程Tool Execution StepsAgent 调用工具获取信息的执行过程Guardrails Steps审核moderation检查的执行过程。这为调试、日志记录和成本分析提供了细粒度的钩子更深层的执行流程可参阅 agent_execution_loop.mdx。三、工具系统ToolGroups 与 ToolRuntimeAgents API 的原始文档明确指出Agents can be provided with various tools (see the ToolGroups and ToolRuntime APIs for more details). 即 Agent 的工具能力来自 OGX 的两套底层 APIToolGroups对工具进行分组管理的 API将相关工具组织成组便于按需装配ToolRuntime工具运行时 API负责工具的实际执行与生命周期。在上面的示例中tools[builtin::code_interpreter, builtin::file_search]即采用builtin::前缀的内置工具组无需额外配置即可使用。OGX 同时支持通过Connectors APIv1beta注册 MCP 等外部工具服务器实现工具生态的扩展见 docs/docs/api-experimental/index.mdx。更完整的工具集成方式可参考 tools.mdx。四、安全护栏Moderation 与 Guardrails根据 docs/supplementary/experimental/agents-api.mdAgents can be configured with moderation and guardrail settings through model and endpoint configuration.即 Agent 的审核与护栏不是通过 Agent 对象自身配置而是通过底层的模型model与端点endpoint配置注入的。这条设计意味着护栏能力复用自 Responses provider 的 guardrails 机制团队可以在网关/端点层面统一管控审核策略而不必在每个 Agent 中重复配置。对照 docs/docs/building_applications/responses_vs_agents.mdx 中的对比表Responses API 通过请求参数guardrailstrue配合已配置的moderation_endpoint启用护栏Agents API 则经由底层 Responses provider 的 guardrails 间接生效。因此在实验性 Agents API 上启用审核实际是在其底层模型/端点配置中设定 moderation 参数。五、记忆与知识库RAG Tool 与 Vector IO实验性 Agents API 的另一项核心能力是记忆Agents can also use Memory to retrieve information from knowledge bases. See the RAG Tool and Vector IO APIs for more details.这里的 Memory 指的不是模型上下文窗口而是从外部知识库检索信息的能力落地依赖两套 APIRAG Tool把检索增强生成封装为 Agent 可调用的工具在src/ogx_api/rag_tool.py中有对应实现Vector IO API对向量库执行添加文档、搜索、删除等操作见 vector_io 系列文档。工作流大致为文档先经 Vector IO 写入向量库Agent 在回合中通过 RAG Tool 检索相关片段再交给 LLM 组织回答。这正是 docs/docs/building_applications/rag.mdx 所描述的知识增强型 Agent路径。仓库还提供了完整的 RAG 基准评测框架见 benchmarking/rag 目录及其配套博客 2026-05-26-rag-benchmarks.md。六、支持的 Provider 与运行形态根据 docs/docs/api/index.mdxAgents API 的受支持 Provider 为Builtin单节点内置实现适合本地开发与轻量部署Fireworks托管云端托管推理Together托管云端托管推理PyTorch ExecuTorch设备端 iOS面向移动端的设备上推理。其中 Builtin 与远程 provider 的执行代码分别位于 src/ogx/providers/inline 与 src/ogx/providers/remote/agents/init.py可据此了解不同形态下的接入差异。仓库的集成测试 tests/integration/agents/test_openai_responses.py 则验证了 Agent 场景与 OpenAI Responses 协议互通的行为。七、实验性 API 的使用注意事项由于该 API 处于预览阶段使用时应关注以下约束接口可能变更OGX 的 Experimental APIs 说明 明确警告实验性 API 可能在 minor 版本中引入破坏性变更若稳定性敏感请锁定客户端版本适合探索与反馈官方欢迎就 API 设计与可用性、性能特征、缺失功能、集成模式四个方面提供反馈渠道见关联文档新项目优先选择稳定接口对于生产应用建议使用具备向后兼容保证的 Responses API它支持标准 OpenAI SDK、动态配置与对话分支。八、小结实验性 Agents API 为 OGX 提供了以Agent指令 工具→ Session会话线程→ Turn交互回合→ Steps可观测过程为骨架的 Agent 编程模型并串联了 ToolGroups/ToolRuntime 工具系统、基于 model/endpoint 配置的 moderation 护栏、以及基于 RAG Tool 与 Vector IO 的知识库记忆。虽然它正逐步让位于更稳定的 Responses API但其抽象设计——尤其是会话内多轮状态 回合级可观测性——依然是理解 OGX Agent 生态的重要入口也为评估与反馈下一代 Agent 接口提供了实验场地。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
