当您需要自定义复杂的业务逻辑、集成现有开发框架（如 LangChain）或对运行环境进行精细化控制时，可以使用“高代码模式”创建 Agent。此模式为您提供最大的开发自由度和工程化能力。
功能介绍
代码创建Agent（高代码模式）用于通过代码自定义 Agent 的实现逻辑，适合有开发经验、对行为和性能有精细控制需求的场景。
在该模式下，开发者可以基于自有代码或框架（如 LangChain 等）实现复杂的推理流程、工具编排和企业级集成能力。
主要能力包括：
支持多种代码来源与运行方式：上传代码包、本地/OSS 代码部署、在线编辑代码，以及使用自定义容器镜像部署 Agent 服务。
支持多语言运行时与自定义启动方式：可选择不同运行时（如 Python、Node.js、Java 等），自行配置启动命令、启动端口和依赖结构。
支持灵活的资源与运行环境配置：可按需配置 CPU / 内存、单实例并发会话上限、会话空闲超时时间，以及 VPC 网络、执行角色、访问凭证、环境变量、健康检查等高级参数。
支持使用 SDK / 框架深度定制：可以直接在代码中使用 AgentRun SDK 接入模型、Sandbox、工具和外部系统，也可以与现有 Agent 框架（如 LangChain 等）集成，实现复杂工作流和业务逻辑。
支持完整的开发调试与运维流程：提供在线 WebIDE、实时日志、基于 OpenAI Chat Completions 协议的调试接口，以及与版本管理、灰度发布配套使用的能力。
高代码模式适合在完成低代码快速验证后，对 Agent 进行工程化落地和持续演进的阶段；当需要复杂逻辑、细粒度控制和与现有系统深度集成时，建议使用高代码模式进行开发。
核心概念
在使用代码创建 Agent 前，建议先了解如下核心概念，如已经提前了解，可以直接进入Agent创建：
核心概念 | 说明 |
代码来源 | 高代码模式支持多种代码来源，用于部署 Agent：
选择哪种方式取决于你的团队习惯和工程实践（例如是否已有 CI/CD 构建镜像流程）。 |
运行时类型 | 创建 Agent 时需要选择运行时语言环境，目前支持：
注意：目前仅 Python 3.10 提供官方模板示例，其他运行时请使用用户自定义代码包或镜像。 |
示例代码包 | 为了帮助用户快速上手，平台提供了基于 AgentRun SDK 编写的示例模板。 官方示例是基于 AgentRun SDK 的 LangChain Agent 示例，包含模型调用和 Sandbox 工具调用的示例代码 |
启动配置 | 对于代码包模式（本地上传 / OSS / 在线编辑），需要指定：
如果使用官方模板，通常保持默认配置即可；如果使用自定义代码，请根据实际入口文件和服务端口填写。 对于容器镜像模式，需要至少指定：
启动命令一般由镜像内 Dockerfile 决定（ |
资源配置 | 资源配置用于控制 Agent 实例的资源规格和并发行为，包括：
合理配置这些参数可以在性能和成本之间取得平衡。 |
高级配置 | 高级配置包含运行时环境相关的选项，例如：
这些配置决定了 Agent 在运行时能访问哪些资源以及如何访问。 |
可观测性 | 支持一键开通智能体可观测，用于观测和分析 Agent 的运行情况：
|
操作指南
准备工作
准备代码工程
准备运行时依赖
确定使用的运行时语言版本（如 Python 3.10、Python 3.12、Node.js 18/20、Java 8/11/17 等）；
官方示例代码使用的运行时为Python3.10
如果使用“代码包”模式：
将代码与依赖一并打包为 zip；
对 Python 项目，建议将依赖放到
/python或/code/python等约定目录；
如果使用“容器镜像”模式：
在镜像中包含完整运行环境和依赖；
在 Dockerfile 中正确配置入口命令和监听端口。
准备模型、工具与沙箱
在模型管理中已创建好需要使用的模型（并记录模型名称）；
如 Agent 需要使用工具（业务 API、网页抓取、在线搜索等），提前在工具管理中完成创建；
如需要代码执行或浏览器能力，提前创建好 Sandbox沙箱服务（BrowserTool浏览器、Code Interpreter代码解释器），并记录服务名称。
步骤1：进入代码创建Agent页面
进入AgentRun运行时与沙箱页面；
点击创建Agent，在弹出的窗口中选择通过代码创建；
输入Agent名称和功能描述，建议使用有意义的名称，便于后续管理和识别；
步骤2：代码配置
选择代码来源
上传代码包
点击上传文件，选择本地 zip；
确保包内结构符合运行时规范（入口文件位置、依赖目录等）；
如基于官方示例，可先下载模板，填入必要配置（如 system_prompt），再打包上传。
说明示例代码中的
MODEL_NAME和SANDBOX_NAME会从运行时环境变量中读取，此处无需修改。
从OSS获取代码包
在代码来源选择OSS 对象存储；
选择 OSS 中的代码包所在的Bucket名称和OSS目录；
确保执行角色具备读取该 OSS 对象的权限。
使用容器镜像部署
在代码来源选择容器镜像；
选择镜像实例与镜像仓库；
说明支持自定义镜像、阿里云容器镜像服务（个人版/企业版）；
当容器镜像实例选择自定义镜像时，可以直接配置自定义镜像地址。
选择镜像版本。
在线编写和调试代码
选择在线编码方式，会在在线代码编辑器中自动加载官方示例代码，您可以直接进行代码业务逻辑实现和修改。
启动配置
上传代码包/OSS对象存储/在线编辑模式
启动命令：例如
python3 main.pynode app.jsjava -jar app.jar
启动端口：例如
9000，需与代码中服务监听端口一致。
如果使用官方模板（如上述 Python 示例），一般默认：
容器镜像模式
启动命令通常由镜像内 Dockerfile 的
CMD/ENTRYPOINT决定；需要在配置中指定 启动端口，与容器内应用监听端口一致。
步骤3：资源配置、环境变量与高级配置
在资源配置和高级配置中设置运行参数。
计算资源
CPU（核）与内存：为每个 Agent 实例分配的计算资源。资源越多，处理复杂任务的速度越快，但成本也相应增加。
单实例并发会话数上限：单个 Agent 实例能同时处理的会话数量。提高此值可以降低所需实例数，从而节约成本，但需确保您的代码是线程安全的，且单个实例的 CPU/内存足以支撑。
会话空闲超时时间（秒）：实例上最后一个会话结束后，空闲超过该时间即自动释放实例。
环境变量：
为 Agent 配置运行时环境变量，用于向代码按需传递参数，如使用官方示例时，需要配置如下环境变量：
MODEL_NAME：必选，需填写模型管理中对应的已创建模型名称；SANDBOX_NAME：可选，对应已创建的 Sandbox 名称；
网络配置
允许访问VPC：如Agent需要访问VPC内的云资源，如RDS、OSS等；
允许默认网卡访问公网。
日志配置
开启日志功能，可以将Agent的运行日志保存在日志服务中，可以指定日志项目（Project）与日志库（Logstore）,也可以选择自动配置或自定义配置中的一件配置功能，使用默认值。
健康检查配置
启用健康检查，可以配置健康检查路径（如
/health）、检查间隔（秒）、超时时间（秒）、失败阈值，系统将定期向指定路径发送HTTP请求检查服务状态，连续失败达到阈值时将自动重启服务实例，有助于提高服务可用性和自动故障恢复。
步骤4：按需配置执行角色
此配置旨在授予您的 Agent 代码访问其他云资源（如模型服务、OSS）的权限。AgentRun 通过 执行角色（一个 RAM 角色）来管理权限，您的代码在运行时会扮演此角色，从而获得相应的操作权限。
授权主体：函数计算服务（fc.aliyuncs.com）
需要的权限：根据实际使用的服务添加相应策略
常用策略：AliyunOSSFullAccess、AliyunVPCFullAccess等
操作：在执行角色ARN中选择角色，如果没有符合要求的角色，可以参考如下步骤进行添加。
单击执行角色ARN下拉框右侧的添加按钮
，进入RAM访问控制>角色列表；点击创建角色；
在创建角色页面，信任主体类型选择云服务；
信任主体名称选择函数计算/FC;
点击确定，输入角色名称，点击确定，并按照提示完成安全验证;
创建成功后，会进入到角色详情页，点击新增授权；
根据实际使用的服务添加相应策略，常用策略示例：
AliyunOSSFullAccess：如Agent需要使用OSS中的资源，需配置管理对象存储服务（OSS）权限；
AliyunVPCFullAccess：管理专有网络（VPC）的权限，如在网络配置中配置了允许访问VPC，此策略必选；
AliyunAgentRunFullAccess：如果使用官方示例进行创建，必须配置管理 AgentRun 服务的权限；
AliyunDevsFullAccess：管理Serverless开发平台（Devs）的权限。
步骤5：配置访问凭证
为 Agent 配置访问入口的凭证（例如 API Key 等），用于保护您的 Agent，防止未经授权的调用。凭证由 AgentRun 的凭证管理统一管理和注入。
在访问凭证模块，点击入站：访问凭证
选择凭证模式：
不使用凭证（不推荐）：Agent 的调用地址可被公网匿名访问，存在安全风险。此模式仅适用于功能测试，严禁用于生产环境。
使用已有凭证（推荐）：为了保障 Agent 安全，建议选择此项。如果您还没有凭证，可以选择已有的凭证，可以点击
参考凭证管理进行创建。
步骤6：完成配置并测试
完成上述步骤后，单击右上角开始部署，即可完成创建。并自动跳转至Agent详情页，选择代码与调试，在调试工具中进行测试。
步骤7：发布版本并进行灰度
AgentRun 支持版本管理与灰度发布。在对 Agent 的提示词、工具或模型进行变更后，建议先 发布版本，然后通过 创建Endpoint 并 启用次要版本（灰度发布），将一小部分 流量分配 给新版本。在监控确认新版本稳定可靠后，再逐步增加流量比例，最终完成全量上线。
在左侧目录中选择版本与灰度；
发布当前版本：点击发布版本，并输入版本描述，描述此版本主要变更和功能后，点击发布版本；
创建Endpoint：
输入Endpoint名称，主要版本下拉框中选择上一步中发布的当前版本号；
启用次要版本（灰度发布）：勾选启用次要版本（灰度发布），选择次要版本，并为主要版本和次要版本配置流量分配百分比；
后续步骤
在应用中集成Agent
在左侧集成与发布模块参考Agent集成与发布文档，将开发的 agent 快速集成到您的前端网页、后端应用等，支持UI集成、代码集成、生态集成三种方式。
开通智能体可观测
在Agent创建后，你可以按需为 Agent 配置可观测能力，便于后续调试和运维。
查看基础监控：默认开启。在左侧目录选择可观测性>基础监控页面，可直接查看
调用次数、成功率、平均/最大延迟；
最近一段时间的调用趋势与延迟曲线。
开启日志采集（推荐）
在 Agent 详情页左侧选择可观测性>日志；
首次进入时会提示日志未开启，点击开通日志；
选择配置方式：
自动配置：一键创建默认的 SLS Project 和 Logstore，适合快速接入；
自定义配置：选择已有 Project / Logstore，适合企业统一日志管理。
保存后，Agent 的运行日志会自动写入对应 Logstore，可在 SLS 控制台进行检索、分析和告警。
接入应用监控与链路追踪（进阶，可选）
首次进入需开通ARMS服务，在可观测性>应用监控（或链路追踪）页面，点击一键开通；
按提示或参考智能体大模型可观测文档，在你的 Agent 代码中引入应用监控，即可进行应用监控与链路追踪：
完成配置后即可在应用监控面板中查看业务指标和趋势（如token 消耗分析、性能分析），在链路追踪面板中查看每次请求的 Span 详情和调用拓扑，快速定位慢请求和异常节点。
常见问题与故障排查
Q1: 启动 Agent 时，日志提示 ModuleNotFoundError: No module named 'xxx'。
A: 这是典型的 Python 依赖缺失问题。请检查：
在使用 上传代码包 模式时，您是否已遵循准备工作中准备运行时依赖 的指导，将所有依赖库打包到代码包的
/python目录下。如果依赖包含 C/C++ 扩展且编译环境复杂，建议切换到容器镜像模式。
Q2: Agent 启动失败，日志显示端口监听错误或超时。
A: 请检查您的代码：
Web 服务是否监听在
0.0.0.0而不是127.0.0.1。代码中监听的端口号是否与您在控制台 启动端口 中配置的一致。最佳实践是从
AGENT_PORT环境变量动态获取端口号。
Q3: 只有 Python 3.10 提供官方模板吗？其他语言如何开始？
A: 是的，目前官方提供的 LangChain 示例模板仅支持 Python 3.10。对于其他运行时（如 Node.js, Java），您需要选择 高代码模式 并上传您自己的自定义代码包或使用自定义镜像。您可以参考官方代码的Python示例，将其逻辑迁移到您选择的语言和框架中，核心是实现一个符合规范的HTTP 服务。