前提:你已经在 AgentRun 上有一个跑起来的 Agent。如果还没有,先看5 分钟上手 AgentRun。
01Agent 做好了,然后呢?
Cloud Native
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,不需要人主动发起对话。
02改两行代码,现有项目直接调通
Cloud Native
其他平台接 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 里可以直接复制。拿到之后,下面几种调法都能通。
Python(用 OpenAI SDK)
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、空闲超时、状态追踪),你不需要自己建会话存…