AI 助理
文档备案控制台
开发者社区 云原生 Serverless 文章 正文

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

2026-06-25 25
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： AgentRun让Agent集成极简：兼容OpenAI协议，改两行代码即接入；支持代码、SDK、UI嵌入、IM机器人、云事件五种集成方式，无需新协议、新SDK。控制台配置即生效，自动具备工具调用、RAG知识库、多轮对话、安全护栏与全链路可观测能力。

前提：你已经在 AgentRun 上有一个跑起来的 Agent。如果还没有，先看 5 分钟上手 AgentRun。

一、Agent 做好了，然后呢？

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 端点，格式大概长这样：

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

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

image.png

Python（用 OpenAI SDK）

python
from openai import OpenAI

client = 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

bash
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。具体示例见 集成文档。

三、AgentRun Python SDK：在代码里管理 Agent 的全生命周期

除了兼容 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 把这些都封装好了。

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

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

python
from agentrun.integration.langchain import model, sandbox_toolset, toolset

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

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

四、UI 集成：不写后端也能嵌

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

三种嵌入方式按场景选：

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

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

image.png

五、IM 集成：Agent 直接变成钉钉/飞书机器人

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

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

image.png

六、事件集成：云上事件自动触发 Agent

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

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

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

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

image.png

七、选哪种集成方式

全屏复制

场景 推荐方式 理由
后端服务调用 Agent OpenAI 兼容端点 改两行代码就通，不引入新依赖
在代码里管理 Agent（创建、更新、灰度） AgentRun Python SDK 管理 API 只有这个 SDK 有
用 LangChain / CrewAI 等框架开发 AgentRun SDK + 对应集成模块 直接拿到框架认识的 model 和 tool 对象
网页里嵌聊天窗口 UI 嵌入 复制代码片段就行，不用写后端
接到钉钉/企微/飞书群 IM 集成 控制台配完就能用，不用写 webhook
云事件自动触发（OSS 文件、告警等） 事件集成 接 EventBridge，不用人主动发起对话

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

回顾：AgentRun 集成为什么省事

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

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

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

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

八、相关链接

文章标签：
开发工具
API
机器人
Python
前端开发
Serverless小助手
目录
相关文章
阿里云安全_
|
3天前
|
云安全 人工智能 运维
阿里云SecOps Agent，全新安全跨产品执行体验
自然语言驱动 云安全中心/WAF/CFW/ 等多款安全产品联动
阿里云安全_
1592 2
bailiantest1
|
3天前
|
机器学习/深度学习 人工智能 调度
🐴 HappyHorse 1.1 现已上线阿里云百炼！快来查收模型使用指南，现在调用享 6 折～
HappyHorse 1.1 是新一代视频生成大模型，全面升级动态表现力、角色一致性、指令遵循、视觉质感与音画协同能力。支持I2V/T2V/R2V三类生成，适配短剧、电商广告、品牌营销等场景，提供高质、流畅、可控的AI视频生产力。
bailiantest1
557 3
🐴 HappyHorse 1.1 现已上线阿里云百炼！快来查收模型使用指南，现在调用享 6 折～
游客37x5chh37o32g
|
14天前
|
缓存 测试技术 API
Qwen 3.7 Plus 与 Max 实测：性价比与多模态能力差异解析（2026）
2026 年 6 月 1 日，阿里悄无声息地发布了 Qwen 3.7 Plus，距 Qwen 3.7 Max 上线刚好 11 天。同样的 1M 上下文，同样的 35 小时自治上限。但价格才是头条：Plus 是 0.40/M输入，Max是 2.50/M——便宜约 6 倍——并且还能看图、看视频。Vision Arena 上 Plus 已经排到 #16。所以这周真正值得讨论的问题不是”要不要为视觉能力买单”，而是”Max 凭什么用 6 倍价格换来 2 个百分点的 benchmark 领先”。
游客37x5chh37o32g
796 14
顾念a
|
15天前
|
JavaScript 定位技术 API
CodeGraph 爆火：编程 Agent 需要的不是更多上下文，而是一张提前画好的代码地图
CodeGraph 是一款爆火的本地代码智能工具，通过 tree-sitter 解析 AST 构建结构化知识图谱（存于 SQLite），为编程 Agent 提前生成“代码地图”。它显著降低 Agent 在中大型项目中的探索成本——实测工具调用减少71%、Token 降57%、速度提升46%，支持19+语言及主流框架路由识别，完全离线、无需 API Key。
顾念a
898 11
CodeGraph 爆火：编程 Agent 需要的不是更多上下文，而是一张提前画好的代码地图
阿里云云原生
|
2天前
|
人工智能 监控 前端开发
Electron 监控：让桌面 Agent 监控触手可及
一行代码实现Electron桌面端全景监控，自动还原崩溃现场、预警内存泄漏、全链路追踪、 SSE流式响应与交互埋点，让 AI 助手运行状态清晰可见，助力快速恢复稳定与流畅。
阿里云云原生
177 126
阿里云云原生
|
2天前
|
消息中间件 人工智能 Kafka
AI 时代，实时入湖正在告别 ETL：从 Kafka 到 Iceberg 的架构减法
本文围绕“零 ETL”这一趋势，讨论流数据入湖为什么需要做架构减法，并结合 Kafka × Table Bucket 的实践，分析一种将通用入湖能力前移到消息与表存储链路中的方案，如何在降低复杂度的同时，兼顾实时性、一致性、Schema 演进、CDC 语义与开放生态兼容。
阿里云云原生
179 121
小鲸云
|
7天前
|
缓存 人工智能 运维
GLM 5.2自托管全流程实战：硬件选型、vLLM/SGLang部署与成本盈亏测算
2026年智谱发布GLM 5.2超大混合专家模型，区别于以往仅开放API的闭源大模型，该模型权重以MIT开源协议对外发布，企业与开发者可完整下载、本地审计、私有化部署，实现数据不出环境、自定义微调、自主调度推理资源。GLM 5.2拥有753B总参数，原生支持百万级上下文窗口，在代码生成、长文档推理、数学逻辑等多项基准测试中对标国际顶尖商用模型，是首款可完整自托管的前沿代码向大模型。
小鲸云
608 0
问号云
|
15天前
|
人工智能 运维 JavaScript
阿里云Qoder CN（原通义灵码）全解析 产品形态、版本划分与技术适配说明
在AI辅助开发与智能办公工具持续普及的当下，阿里云旗下原通义灵码正式更名为Qoder CN，同时延伸出QoderWork CN、Qoder CN CLI、Qoder CN Mobile等多款配套产品，形成覆盖代码开发、日常办公、终端交互、移动端使用的完整工具矩阵。Qoder CN核心定位为AI智能编码助手，深度适配主流代码编辑器、集成开发环境以及终端场景；QoderWork CN则偏向桌面端综合办公辅助，二者面向不同使用场景，划分了多个版本档位，搭配差异化资源配额、功能权限与计费规则，同时兼容多款主流大模型。
问号云
969 8
云原生

Serverless

热门文章

最新文章

  • 1
    开发函数计算的正确姿势 —— 移植 next.js 服务端渲染框架
  • 2
    thinkphp项目迁移到函数计算
  • 3
    快速搭建基于 Serverless 的 .NET Core 数据库应用
  • 4
    首次揭秘：阿里巴巴中间件在 Serverless 技术领域的探索
  • 5
    10分钟-使用阿里云函数计算构建你的OCR智能识别云端小程序
  • 6
    玩转阿里云函数计算(一)----Java Http 触发器极速迁移传统 Spring 应用
  • 7
    入门篇：函数计算的基本概念和通用场景概述
  • 8
    php runtime 中 headers already sent 问题解决方案
  • 9
    开发函数计算的正确姿势 —— 使用 ROS 进行资源编排
  • 10
    实践篇：搭建无服务器应用--函数计算+API网关+云市场（提供手机号归属地查询服务）
  • 1
    用两行代码将 AgentRun 集成到你的应用
    25
  • 2
    光聪明还不够，Agent “真干活”还缺一套趁手的工具
    34
  • 3
    光聪明还不够，Agent “真干活”还缺一套趁手的工具
    57
  • 4
    从单兵作战到团队协作：AgentRun 的多 Agent 生产级协作方案
    109
  • 5
    复杂税率计算器的工程化实践：Next.js、现金流建模与多层缓存
    92
  • 6
    Next.js 核心解析：一文搞懂 SSR、SSG 与 ISR 渲染策略选择
    172
  • 7
    用两行代码将 AgentRun 集成到你的应用
    277
  • 8
    5 分钟上手 AgentRun：从注册到第一个 Agent 运行
    372
  • 9
    5 分钟上手 AgentRun：从注册到第一个 Agent 运行
    381
  • 10
    Agent 从“能用”到“管好”，中间差了什么？
    302

    • 相关电子书

    更多
  • 低代码开发师（初级）实战教程
  • 冬季实战营第三期：MySQL数据库进阶实战
  • 阿里巴巴DevOps 最佳实践手册
    • 下一篇
    小红书笔记详情API深度解析与实战指南（2025年最新版）