用两行代码将 AgentRun 集成到你的应用

推荐语

AgentRun 让 AI Agent 集成变得简单，只需两行代码即可将你的 Agent 接入现有应用。

核心内容：
1. AgentRun 如何通过兼容 OpenAI 协议简化集成流程
2. Agent 运行时提供的强大后端能力（工具、知识库、记忆等）
3. 覆盖代码、UI、IM、事件等五种集成路径

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

Agent 在控制台测试面板里对话正常，下一步就是接到自己的系统里——后端服务、IM 机器人、小程序、内部工具，都行。

但一般到这一步，事情会变多：多数 Agent 平台需要你先读懂自定义 API 文档、封装 SDK、处理鉴权和流式输出，再用对应语言封装一遍。如果平台用的是自定义协议，还得专门写一套请求和解析逻辑。光对接调通可能就要半天。

AgentRun 没有让你适应新协议，而是选择了让你用现有代码直接调用。每个 Agent 的调用端点直接兼容 OpenAI Chat Completions 协议（同时也支持 AGUI）。如果你的项目已经在使用 OpenAI，把 base_url 换一下，Agent 就接上了——不需要学新协议、不需要装新 SDK、现有的代码一行都不用改。

但接口简单不代表背后能力简单。通过这个端点调用的不是一个裸模型，而是一个完整的 Agent 运行时——它可以挂载工具（MCP Server、Function Call、Skill 三种类型统一管理）、接入知识库（支持本地文件、OSS、飞书文档、百炼、Ragflow 等多种数据源做 RAG 检索增强）、使用长短期记忆保持上下文连贯性，还内置了内容安全护栏和基于 OpenTelemetry 的全链路可观测。这些能力在控制台配置好之后，调用方不需要感知，一个标准的 OpenAI 请求就能触发整个链路。

调用只是起点。AgentRun 在集成这件事上提供了五条路径，覆盖从后端代码到前端页面、从 IM 群聊到云事件触发的全部场景：

• 代码集成：兼容 OpenAI 协议，改两行参数就能调通，Python / Node.js / Java / curl 都行。
• SDK 集成：在代码里直接管理 Agent 生命周期、调用沙箱和知识库，无缝对接 LangChain 等主流框架。
• UI 嵌入：四套视觉风格、三种嵌入方式，复制代码片段就能把聊天窗口嵌进网页，不用写后端。
• IM 集成：控制台配完钉钉 / 飞书 / 企微机器人就能用，不用自己写 webhook 转发。
• 事件集成：接阿里云 EventBridge，云上事件自动触发 Agent，不需要人主动发起对话。

其他平台接 Agent，通常要看专属 API 文档、装专属 SDK、处理专属的鉴权和流式协议。AgentRun 不一样：端点直接兼容 OpenAI 协议，你项目里已有的 openai 调用逻辑一行不用改。

每个 AgentRun Agent 创建后都会生成一个固定的 HTTPS 端点，格式大概长这样：

https://{account-id}.agentrun-data.{region}.aliyuncs.com/agent-runtimes/{agent-name}/endpoints/{endpoint-name}/invocations

这个地址在控制台详情页的「集成与发布」→「代码集成」Tab 里可以直接复制。拿到之后，下面几种调法都能通。

from openai import OpenAIclient = OpenAI(    base_url="https://{your-endpoint}/openai/v1",    api_key="your-agentrun-token",       # 控制台「集成与发布」里拿)response = client.chat.completions.create(    model="default",    messages=[{"role": "user", "content": "帮我查一下杭州明天的天气"}],    stream=True,)for chunk in response:    if chunk.choices[0].delta.content:        print(chunk.choices[0].delta.content, end="")

如果你的项目里本来就有 openai 这个包，改的就是 base_url 和 api_key 两个参数——其他代码一行不动。流式、多轮对话、function calling 都走同一套协议。

虽然调用方式和 OpenAI 一样简单，但端点背后跑的不是单纯的模型转发。请求会经过 AgentRun 的 AI 网关，自动处理模型路由、多 APIKey 负载均衡和内容安全检测（输入输出都会过安全护栏），这些能力对调用方完全透明——你不需要额外配置，也不需要改请求格式。模型供应商的 API Key 由平台统一托管和轮转，调用方拿到的是 AgentRun 自己的 token，不会直接接触底层模型密钥，也不用担心密钥泄露后的爆炸半径。

多轮对话：在请求头里加 x-agentrun-session-id: {你的会话ID}，同一个 session-id 下的消息会自动关联上下文。不传的话每次都是独立对话。AgentRun 把 Session 当作平台级资源管理——每个 Session 有独立的生命周期（TTL、空闲超时、状态追踪），你不需要自己建会话存储或写过期清理逻辑，平台全包了。

curl https://{your-endpoint}/openai/v1/chat/completions \  -X POST \  -H "Content-Type: application/json" \  -H "x-agentrun-session-id: {your-session-id}" \  -d '{    "messages": [{"role": "user", "content": "帮我查一下杭州明天的天气"}],    "stream": true  }'

调试阶段拿 curl 先跑通一遍，确认 Agent 返回正常，再往代码里搬。

因为走的是标准 OpenAI 协议，Node.js 用 openai 包同样改 baseURL 和 apiKey 两个参数就通；Java 用任意 HTTP 客户端 POST 到端点地址即可，不需要专门的 SDK。具体示例见集成文档^[1]。

除了兼容 OpenAI、能应付大多数调用场景的接口，AgentRun Python SDK 让你能在代码里管理平台上的全部资源：

• Agent Runtime：创建、更新、删除、版本发布、灰度切流。
• 工具：MCP Server、Function Call、Skill 三种类型通过统一的 CRUDL 接口管理，凭证（API Key、OAuth Token 等）由平台托管，不需要硬编码到工具代码里。
• 模型服务：多供应商统一接入（百炼、自部署模型、第三方 API 都支持），一个 Model 资源搞定注册、治理策略和调用入口。
• Sandbox / Template：代码沙箱的生命周期管理，支持代码解释器、Browser Session、ComputerUse 桌面沙箱等多种环境。
• 知识库 / 记忆：知识库支持多数据源 RAG，记忆模块支持长短期记忆和自定义 Embedding 模型。

SDK 同时提供 LangChain、CrewAI、AgentScope 等主流框架的集成模块。自己用开源框架搭这套东西，光是把各个模块的 API 串起来就得写不少对接代码；SDK 把这些都封装好了。

pip install agentrun-sdk                          # 基础能力pip install agentrun-sdk[langchain,playwright,mcp] # 按需加 LangChain / 沙箱 / MCP

一个典型场景——在 LangChain 里直接用 AgentRun 的模型和工具，不用自己写转换逻辑：

from agentrun.integration.langchain import model, sandbox_toolset, toolsetllm = model(model_name="my-model-service")                       # 拿到 LangChain 识别的 modelcode_tools = sandbox_toolset(template_name="my-sandbox")          # 沙箱（代码解释器）fc_tools = toolset(tool_names=["my-search-tool"])                 # MCP / Function Call 工具# 接下来正常写 LangChain Agent 逻辑就行

安装选项、认证配置、更多代码示例见 SDK 文档^[2]。

自己从零搭一个 Agent 聊天界面，要处理 WebSocket / SSE 长连接、消息渲染、会话管理、样式适配——前端工作量不小。AgentRun 把这些都做成了现成的嵌入组件，控制台「集成与发布」Tab 里直接复制代码片段，贴到 HTML 里改个 token 就能用，不需要写任何后端代码。

三种嵌入方式按场景选：

• 全屏嵌入：适合独立的 Agent 页面。
• 浮动气泡：页面右下角的对话窗口。
• 侧边栏：从右侧滑出的面板。

还有四套视觉风格可选（简约 / 商务 / 科技 / 温馨），不用自己调 CSS 就能跟现有页面风格搭上。

把 Agent 接到 IM 平台，常规做法是自己搭一个 webhook 服务：接收 IM 回调、转发给 Agent、再把结果推回去。麻烦的是，钉钉、飞书、企业微信三家的回调格式、消息卡片结构和鉴权方式都不一样，适配一个平台就要写一套，三个平台就是三套。AgentRun 内置了 IM 通信协议代理，统一处理了三家平台的协议差异——控制台「集成与发布」的 IM 集成 Tab 里点「添加机器人」，按引导填完配置就行，不用自己写一行对接代码。

配置好之后，用户在群聊里 @机器人、私聊对话、发卡片消息都能触发 Agent 回复。多轮对话也不用操心：平台会自动把 IM 里的会话关系映射到 AgentRun 的 Session——比如在飞书里，话题内的回复会自动延续同一个对话上下文，发一条新消息则开启新会话，跟用户在 IM 里的使用习惯完全一致，不需要调用方做任何 session 管理。

前面几种集成方式都需要有人（或代码）主动发起对话。但有些场景不需要人参与——云上发生了某个事件，Agent 自己就该动起来。

事件集成 Tab 可以把 Agent 接到阿里云 EventBridge 事件总线上。EventBridge 能接收 200 多种阿里云服务的事件，配好事件规则之后，你可以让 Agent 在特定事件发生时自动执行。几个典型场景：

• OSS 新增文件 → Agent 自动提取摘要、打标签、归档。
• 云监控触发告警 → Agent 自动分析根因、生成处置建议。
• 数据库表变更 → Agent 自动做数据校验或通知相关人员。
• ECS 实例状态变化 → Agent 自动检查并执行运维操作。

不需要自己写事件消费逻辑，控制台里选好事件源、事件类型和目标 Endpoint，规则就生效了。鉴权也不用管——EventBridge 通过绑定的 RAM 角色自动完成请求签名，不需要你在规则里配 API Key 或手动构造签名逻辑。Agent 的运行时参数（用哪个模型、挂哪些工具、沙箱配置）统一在 AgentRun 侧管理，改了 Agent 配置不需要回 EventBridge 改规则。

大多数场景下，OpenAI 兼容端点就够了。需要更多控制（管理 Agent、调沙箱、用知识库）的时候再上 SDK。

上面五条路径背后是同一个思路：不让你学新东西。

• 代码集成不发明新协议，直接兼容 OpenAI，改两行参数就通，现有代码一行不动。
• SDK 把 Agent 管理、沙箱、知识库、主流框架对接封装到一个包里，不用自己逐个对接。
• UI 嵌入把前端聊天组件做成现成的代码片段，复制粘贴就能用，不用处理 WebSocket 和消息渲染。
• IM 集成内置了 webhook 转发，控制台配完机器人就上线，不用自己搭中间服务。
• 事件集成直接接 EventBridge，云上事件自动触发 Agent，不需要人主动发起对话。

而且这些路径背后共享同一套平台基础设施：AI 网关自动做模型路由、APIKey 轮转和负载均衡；内容安全护栏默认对输入输出做检测；多轮对话通过 session-id 自动关联上下文，Session 有完整的生命周期管理；工具调用、知识库检索、记忆读写这些 Agent 核心能力，在控制台配置好之后就随端点一起生效；基于 OpenTelemetry 的全链路可观测开箱即用，调用出了问题可以直接看 Trace。这些能力不需要你额外集成，调通的那一刻就已经在工作了。

如果你用其他 Agent 平台，这些事情里至少有一半得自己写。AgentRun 把集成这件事的门槛拉到了“能调 OpenAI 就能调 Agent”的程度。

https://help.aliyun.com/zh/functioncompute/fc/what-is-agentrun