本地开发与发布指南

本指南将带您深入了解 AgentRun 应用的完整开发生命周期。从本地环境搭建到云端部署，再到版本管理和灰度发布，您将掌握构建生产级 Agent 应用所需的全部技能。我们将循序渐进地介绍每个环节的原理和最佳实践,帮助您在实际项目中游刃有余。

理解开发工作流程

在开始配置环境之前,让我们先了解 AgentRun 的开发工作流程。整个流程可以分为四个阶段:首先在本地环境中开发和调试 Agent 逻辑,这个阶段您可以快速迭代和验证想法;然后通过 Serverless Devs 工具构建部署包,确保代码与云端运行环境兼容;接着将应用部署到 AgentRun 平台,享受平台提供的弹性伸缩和高可用能力;最后通过版本管理和端点配置实现灰度发布,确保新功能平稳上线。

这种工作流程的设计充分考虑了开发效率和生产稳定性的平衡。本地开发环境让您能够快速验证想法,而云端部署则提供了企业级的可靠性保障。两者之间通过 Serverless Devs 工具无缝衔接,最大限度降低了从开发到生产的摩擦。

准备开发环境

开发 AgentRun 应用需要准备三个关键组件:Serverless Devs 部署工具、Python 运行时环境和 Docker 容器引擎。这些工具各司其职,共同构成了完整的开发工具链。

安装 Serverless Devs 工具

Serverless Devs 是阿里云提供的 Serverless 应用开发平台,它为 AgentRun 提供了项目脚手架、本地调试和云端部署能力。作为命令行工具,它通过简洁的命令抽象了复杂的云端操作,让您能够专注于业务逻辑而非基础设施管理。

使用 npm 全局安装 Serverless Devs 是最推荐的方式,因为 npm 会自动处理依赖关系并将命令添加到系统路径:

npm install -g @serverless-devs/s

安装完成后,验证工具是否可用:

s --version

如果命令正常输出版本号,说明 Serverless Devs 已成功安装。这个工具将贯穿整个开发流程,从项目初始化到部署上线都离不开它。

配置 Python 环境

AgentRun 支持 Python 3.10 及以上版本作为运行时。Python 是 AI 开发的首选语言,拥有丰富的机器学习和 Agent 开发框架。确保您的系统安装了合适的 Python 版本:

python3 --version

如果版本低于 3.10,建议通过系统包管理器或 pyenv 升级到最新版本。此外,我们强烈推荐安装 uv 工具来管理 Python 依赖。uv 是新一代的 Python 包管理器,它使用 Rust 编写,比传统的 pip 快数十倍,能够显著提升依赖安装速度:

curl -LsSf https://astral.sh/uv/install.sh | sh

当然,如果您更习惯使用 pip,它同样可以胜任依赖管理工作。选择哪种工具取决于您的个人偏好和团队规范。

准备 Docker 环境

Docker 在 AgentRun 开发流程中扮演着重要角色。当您执行 s build 命令时,Serverless Devs 会在 Docker 容器中安装项目依赖。这种方式确保了本地构建的代码包与云端运行环境完全一致,避免了"在我机器上可以运行"的经典问题。

验证 Docker 是否正常运行:

docker --version
docker ps

如果 Docker 尚未安装,请访问 Docker 官网下载适合您操作系统的版本。安装完成后,确保 Docker 服务处于运行状态。

配置云端访问凭证

与 AgentRun 平台交互需要两组不同的访问凭证,理解它们的区别很重要。第一组是部署凭证,用于 Serverless Devs 工具调用阿里云 API 执行部署操作,包括创建 Agent Runtime、配置端点、管理版本等。第二组是运行时凭证,嵌入到 Agent 应用中,用于运行时访问 AgentRun 的服务资源,如调用模型服务、创建沙箱实例、使用工具集等。

首先配置部署凭证。在终端执行配置命令:

s config add

这个命令会启动交互式配置向导,按照提示依次输入您的阿里云账号信息。为这组凭证设置一个有意义的别名,例如 agentrun-deploy,这样在多账号或多环境场景下可以轻松切换。配置完成后,可以通过 s config get 命令查看已保存的凭证列表。

运行时凭证的配置稍后会在项目初始化章节中介绍,因为它们需要写入到项目的环境变量文件中。

初始化项目结构

环境准备就绪后,就可以创建您的第一个 AgentRun 项目了。AgentRun 提供了精心设计的项目模板,包含了开箱即用的代码结构和配置文件,可以帮助您快速启动开发工作。

使用脚手架生成项目

执行项目初始化命令:

s init agentrun-quick-start-langchain

这个命令从官方模板仓库下载 LangChain 框架的快速启动模板。模板选择取决于您偏好的 AI 开发框架,AgentRun 支持 LangChain、AgentScope、LangGraph、CrewAI 等多个主流框架。对于初学者,LangChain 是最佳选择,因为它拥有最完善的文档和最活跃的社区。

命令执行后会在当前目录创建 agentrun-quick-start-langchain 文件夹。进入项目目录并安装依赖:

cd agentrun-quick-start-langchain/code

如果您安装了 uv 工具,使用以下命令创建虚拟环境并安装依赖:

uv venv && uv pip install -r requirements.txt

uv 会在几秒钟内完成依赖安装,速度远超传统的 pip。如果您使用 pip,则执行:

python3 -m venv venv
source venv/bin/activate  # Windows 系统使用 venv\Scripts\activate
pip install -r requirements.txt

虚拟环境的使用是 Python 开发的最佳实践,它将项目依赖与系统 Python 环境隔离,避免了版本冲突问题。

理解项目的组织结构

让我们深入了解项目模板的结构设计。项目根目录包含两个核心部分:

agentrun-quick-start-langchain/
├── code/                    # Agent 应用代码目录
│   ├── app.py              # 应用程序主入口
│   ├── requirements.txt    # Python 依赖声明文件
│   └── .env                # 运行时环境变量配置(需要手动创建)
└── s.yaml                  # Serverless Devs 部署配置文件

code 目录是您编写业务逻辑的地方。app.py 文件定义了 Agent 的核心行为,包括模型配置、工具加载、请求处理等。打开这个文件,您会看到清晰的代码结构:

from agentrun.integration.langchain import model, sandbox_toolset
from agentrun.sandbox import TemplateType
from agentrun.server import AgentRequest, AgentRunServer
from agentrun.utils.log import logger

# 配置模型和沙箱资源
MODEL_NAME = "<your-model-name>"
SANDBOX_NAME = "<your-sandbox-name>"

# 验证配置有效性
if MODEL_NAME.startswith("<"):
    raise ValueError("请将 MODEL_NAME 替换为您已经创建的模型名称")

# 加载沙箱工具集
code_interpreter_tools = []
if SANDBOX_NAME and not SANDBOX_NAME.startswith("<"):
    code_interpreter_tools = sandbox_toolset(
        template_name=SANDBOX_NAME,
        template_type=TemplateType.CODE_INTERPRETER,
        sandbox_idle_timeout_seconds=300,
    )
else:
    logger.warning("SANDBOX_NAME 未设置或未替换，跳过加载沙箱工具。")

# 启动 HTTP 服务器监听请求
AgentRunServer(invoke_agent=invoke_agent).start()

这段代码完成了三个关键任务。首先从 AgentRun 平台获取模型和沙箱资源,并将它们转换为 LangChain 框架所需的格式。然后定义 Agent 的处理逻辑,决定如何响应用户请求。最后启动一个 HTTP 服务器,在 9000 端口监听外部请求,提供 OpenAI 兼容的 API 接口。

requirements.txt 文件声明了项目的 Python 依赖,包括 AgentRun SDK、LangChain 框架等。s.yaml 则是 Serverless Devs 的配置文件,定义了如何将应用部署到云端,包括资源规格、环境变量、网络配置等。

创建和配置云端资源

在本地运行 Agent 之前,您需要在 AgentRun 控制台创建必要的云端资源。这些资源为 Agent 提供了实际的计算能力,本地开发时通过 API 调用它们,部署到云端后同样使用这些资源。

创建模型服务

模型是 Agent 的"大脑",负责理解用户意图、规划执行步骤、生成回复内容。登录 AgentRun 控制台,进入模型管理页面,根据您的需求选择创建模型服务或模型代理。

模型服务用于接入您自己部署的模型,这种方式给予您完全的控制权,适合有特殊定制需求或数据安全要求的场景。模型代理则用于接入第三方模型 API,如 OpenAI GPT-4、阿里云通义千问、百度文心一言等,这种方式配置简单,可以快速开始开发。

创建完成后,记录下模型的名称,例如 my-model。这个名称将在代码中用于引用该模型资源。

创建沙箱模板

沙箱为 Agent 提供了安全的代码执行环境。在代码解释器场景下,Agent 可以编写 Python 代码并在沙箱中运行,从而具备数据计算、文件处理等能力。在浏览器场景下,Agent 可以控制无头浏览器访问网页、提取信息,实现网页自动化操作。

在控制台创建沙箱模板时,选择 Python 3.10 或更高版本作为运行时,确保与您的本地开发环境版本一致。配置合适的资源规格,通常 1 核 2GB 内存足以应对大多数任务。根据 Agent 的需求决定是否允许沙箱访问公网,如果需要调用外部 API 或下载数据,则需要开启网络访问。

创建完成后,记录沙箱模板的名称,例如 my-sandbox。

配置项目代码

现在将云端资源名称填入项目代码。打开 code/app.py 文件,找到模型和沙箱配置部分:

MODEL_NAME = "my-model"      # 替换为您创建的模型名称
SANDBOX_NAME = "my-sandbox"  # 替换为您创建的沙箱模板名称

这些配置告诉 AgentRun SDK 使用哪些云端资源。SDK 会自动处理与这些资源的交互细节,您只需关注业务逻辑即可。

接下来配置运行时凭证。在 code 目录下创建 .env 文件:

AGENTRUN_ACCESS_KEY_ID=your-access-key-id
AGENTRUN_ACCESS_KEY_SECRET=your-access-key-secret
AGENTRUN_ACCOUNT_ID=your-account-id
AGENTRUN_REGION=cn-hangzhou

将其中的值替换为您的实际凭证信息。这些环境变量在本地开发时由 .env 文件提供,部署到云端后则通过 s.yaml 的配置注入。需要特别注意的是,.env 文件包含敏感信息,绝不应该提交到 Git 仓库。建议在 .gitignore 文件中明确排除它,并创建一个 .env.example 文件作为模板,只包含配置项的名称而不包含实际值。

本地开发和调试

配置完成后,就可以在本地启动 Agent 服务进行开发和测试了。本地开发环境的优势在于快速反馈,您可以立即看到代码修改的效果,无需等待漫长的部署过程。

启动本地服务

在 code 目录下,首先激活虚拟环境(如果使用):

source venv/bin/activate  # Windows 系统使用 venv\Scripts\activate

然后启动应用:

python app.py

程序启动后,会输出类似以下的日志信息:

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:9000

这表示 HTTP 服务器已成功启动,正在 9000 端口监听请求。AgentRun SDK 使用 Uvicorn 作为 ASGI 服务器,它是 Python 异步 Web 应用的标准选择,性能优异且稳定可靠。

服务运行在前台,您可以实时看到所有的请求日志和错误信息。这对于开发调试非常有帮助,您能够清楚地了解 Agent 的思考过程、工具调用情况和执行结果。

测试 Agent 功能

打开另一个终端窗口,使用 curl 命令测试 Agent。这里我们使用 OpenAI 兼容的 Chat Completions API,这是业界标准接口,大多数 AI 客户端库都支持它:

curl 127.0.0.1:9000/openai/v1/chat/completions \
  -XPOST \
  -H "content-type: application/json" \
  -d '{"messages": [{"role": "user", "content": "通过代码查询现在是几点?"}], "stream":true}'

这个请求模拟用户提问"现在是几点"。Agent 收到请求后,会经历一系列的推理过程。首先分析问题,判断需要使用代码工具来获取当前时间;然后生成一段 Python 代码,例如 import datetime; print(datetime.datetime.now());接着将代码提交到沙箱执行;最后获取执行结果,并将其转换为自然语言回复返回给用户。

由于请求中设置了 "stream":true,响应会以流式方式返回。您可以看到 Agent 的思考过程逐步展开,就像与人类专家对话一样。这种流式输出大大改善了用户体验,避免了长时间等待的焦虑感。

您可以尝试更多样化的测试来验证 Agent 的能力。例如测试数学计算:

curl 127.0.0.1:9000/openai/v1/chat/completions \
  -XPOST \
  -H "content-type: application/json" \
  -d '{"messages": [{"role": "user", "content": "帮我计算斐波那契数列的第20项"}], "stream":true}'

或者测试数据处理能力:

curl 127.0.0.1:9000/openai/v1/chat/completions \
  -XPOST \
  -H "content-type: application/json" \
  -d '{"messages": [{"role": "user", "content": "生成一个包含10个随机数的列表并计算平均值"}], "stream":true}'

这些测试帮助您验证 Agent 是否能够正确理解问题、选择合适的工具、生成可执行的代码,并将结果清晰地呈现给用户。

调试技巧和最佳实践

在本地开发过程中,您可能会遇到各种问题。掌握一些调试技巧可以大大提高效率。

如果需要查看更详细的日志信息,可以在 .env 文件中设置日志级别:

LOG_LEVEL=DEBUG

DEBUG 级别会输出 SDK 内部的详细执行信息,包括 API 调用参数、响应内容等,这对于诊断问题非常有帮助。但在生产环境中应该使用 INFO 或 WARNING 级别,避免产生过多的日志数据。

对于复杂的逻辑问题,Python 的内置调试器 pdb 是强大的工具。在需要暂停执行的地方插入断点:

import pdb; pdb.set_trace()

程序运行到这里会暂停,您可以交互式地检查变量值、执行表达式、单步执行代码等。

如果怀疑环境变量配置有问题,可以快速验证:

python -c "import os; print(os.environ.get('AGENTRUN_ACCESS_KEY_ID'))"

这个命令会输出当前环境中的 AccessKey ID,帮助您确认环境变量是否正确加载。

本地测试通过后,就可以准备将 Agent 部署到云端了。但在部署之前,让我们先深入理解部署配置文件的结构。

配置部署参数

项目根目录的 s.yaml 文件是 Serverless Devs 的配置文件,它定义了 Agent Runtime 的所有部署参数。理解这个文件的结构对于自定义部署非常重要。

理解基础配置结构

一个典型的 s.yaml 文件包含以下几个部分:

edition: 3.0.0
name: my-agentrun-app
access: default  # 引用 s config add 配置的凭证别名

resources:
  my-agent:
    component: agentrun
    props:
      region: cn-hangzhou
      
      agent:
        name: my-agent-runtime
        description: "My Agent Runtime"
        
        code:
          src: ./code
          language: python3.12
          command:
            - python3
            - app.py
        
        cpu: 1.0
        memory: 2048
        port: 9000
        
        role: acs:ram::{your-account-id}:role/agentRunRole

配置文件采用 YAML 格式,层次清晰且易于理解。edition 指定配置文件的格式版本,name 是应用的标识符。access 字段引用之前通过 s config add 配置的凭证,Serverless Devs 会使用这组凭证来调用阿里云 API。

resources 部分定义了要部署的资源,可以包含多个 Agent Runtime。每个 Resource 需要指定 component: agentrun,表示使用 AgentRun 组件进行部署。

props.agent 部分定义了 Agent Runtime 的具体配置。code 字段有三种配置方式:从本地目录部署(src)、从 OSS 代码包部署(ossBucketName 和 ossObjectName)、或使用自定义容器镜像(customContainerConfig)。对于大多数场景,从本地目录部署是最简单直接的方式。

资源配置(cpu、memory)决定了 Agent 实例的计算能力。合理配置这些参数很重要:配置过低会导致性能问题,配置过高则会增加成本。建议从较小的配置开始,根据实际运行情况逐步调整。

配置 RAM 角色权限

role 字段指定 Agent Runtime 运行时使用的 RAM 角色。这个角色需要具备访问 AgentRun 服务的权限,包括调用模型、创建沙箱、使用工具集等。AgentRun 提供了快速授权链接,可以自动创建具有合适权限的角色。

点击快速授权链接后,系统会引导您创建名为 agentRunRole 的角色,并自动附加必要的权限策略。

创建完成后,将角色 ARN 填入配置文件:

role: acs:ram::123456789:role/agentRunRole  # 将 123456789 替换为您的阿里云账号 ID

角色 ARN 的格式固定为 acs:ram::{账号ID}:role/{角色名称}。您可以在 RAM 控制台查看角色的完整 ARN。

高级配置选项详解

除了基础配置,AgentRun 还支持许多高级特性,适用于更复杂的部署场景。

如果您的 Agent 需要定制的系统依赖或特殊的运行环境,可以使用容器镜像部署:

agent:
  name: my-container-agent
  
  customContainerConfig:
    image: registry.cn-hangzhou.aliyuncs.com/namespace/my-agent:latest
    command:
      - python3
      - app.py
    port: 9000
  
  cpu: 2.0
  memory: 4096

这种方式下,您需要先构建 Docker 镜像并推送到阿里云容器镜像服务。镜像中应该包含完整的运行环境,包括 Python 运行时、依赖包、应用代码等。容器模式提供了最大的灵活性,但也增加了维护复杂度。

对于需要访问数据库或其他内网资源的 Agent,可以配置 VPC 网络:

agent:
  name: my-vpc-agent
  
  code:
    src: ./code
    language: python3.12
    command: [python3, app.py]
  
  vpcConfig:
    vpcId: vpc-bp1234567890abcdef
    vSwitchIds:
      - vsw-bp1111111111111111
      - vsw-bp2222222222222222
    securityGroupId: sg-bp1234567890abcdef
  
  internetAccess: true

VPC 配置将 Agent 实例部署到您的虚拟私有网络中,实现网络隔离和安全访问控制。vSwitchIds 可以配置多个交换机,平台会在这些交换机中均匀分配实例,实现高可用部署。internetAccess: true 表示实例同时具有公网和内网访问能力,如果设为 false 则只能访问内网资源。

如果需要持久化日志并进行分析,可以配置 SLS 日志服务:

agent:
  name: my-agent
  
  logConfig:
    project: my-sls-project
    logstore: agentrun-logs
  
  role: acs:ram::123456789:role/agentRunRole

配置日志服务后,Agent 的所有输出都会自动采集到 SLS,您可以使用 SLS 的强大分析能力进行日志查询、统计、告警等操作。这对于生产环境的可观测性至关重要。

多环境配置策略

在实际项目中,通常需要维护多个部署环境,例如开发环境用于日常开发和测试,生产环境用于正式服务用户。为每个环境创建独立的配置文件是最佳实践。

创建开发环境配置文件 s.dev.yaml:

edition: 3.0.0
name: dev-agentrun-app
access: default

vars:
  region: cn-hangzhou
  env: dev

resources:
  my-agent:
    component: agentrun
    props:
      region: ${vars.region}
      agent:
        name: agent-${vars.env}
        
        code:
          src: ./code
          language: python3.12
          command: [python3, app.py]
        
        cpu: 1.0
        memory: 2048
        
        environmentVariables:
          ENVIRONMENT: ${vars.env}
          LOG_LEVEL: debug
        
        role: acs:ram::123456789:role/agentRunRole

开发环境通常使用较低的资源配置,启用详细的日志级别,方便调试问题。vars 部分定义的变量可以在配置中通过 ${vars.变量名} 引用,避免重复配置。

生产环境配置文件 s.prod.yaml 则需要更高的资源规格和更严格的安全配置:

edition: 3.0.0
name: prod-agentrun-app
access: production

vars:
  region: cn-hangzhou
  env: prod

resources:
  my-agent:
    component: agentrun
    props:
      region: ${vars.region}
      agent:
        name: agent-${vars.env}
        
        code:
          src: ./code
          language: python3.12
          command: [python3, app.py]
        
        cpu: 2.0
        memory: 4096
        instanceConcurrency: 50
        
        vpcConfig:
          vpcId: ${env(VPC_ID)}
          vSwitchIds: [${env(VSWITCH_ID)}]
          securityGroupId: ${env(SECURITY_GROUP_ID)}
        internetAccess: true
        
        environmentVariables:
          ENVIRONMENT: ${vars.env}
          LOG_LEVEL: info
        
        logConfig:
          project: prod-logs
          logstore: agentrun-runtime
        
        role: acs:ram::123456789:role/agentRunRole

注意生产环境使用了 VPC 配置实现网络隔离,配置了日志服务实现可观测性,并且使用 ${env()} 语法从环境变量读取敏感配置,避免将它们硬编码到配置文件中。

通过 -t 参数可以指定使用哪个配置文件部署:

s deploy -t s.dev.yaml   # 部署到开发环境
s deploy -t s.prod.yaml  # 部署到生产环境

这种多环境配置策略既保证了环境隔离,又便于统一管理。

构建和部署应用

配置文件准备就绪后,就可以开始构建和部署流程了。构建过程会将您的代码和依赖打包成可部署的格式,部署过程则将包上传到 AgentRun 平台并创建运行时实例。

构建部署包

在项目根目录执行构建命令:

s build

这个命令的执行过程比较复杂但非常重要。Serverless Devs 首先拉取一个与云端运行环境相同的 Docker 镜像,然后在容器中安装 requirements.txt 中声明的所有依赖包。这种方式确保了构建产物与云端环境完全兼容,避免了因本地环境差异导致的部署失败。

构建过程可能需要几分钟,具体时间取决于依赖包的数量和大小。构建产物会保存在 .s 目录中,包含了代码文件和所有依赖的二进制文件。您可以查看这个目录了解构建结果,但通常不需要手动修改它。

构建成功后,终端会输出确认信息:

Building agent: my-agent-runtime
✅ Build completed successfully

如果构建失败,请仔细阅读错误信息。常见的问题包括:Docker 服务未启动、requirements.txt 中的包不存在或版本冲突、网络连接问题导致包下载失败等。

部署到云端环境

构建完成后,执行部署命令:

s deploy

如果您配置了多个凭证,需要通过 -a 参数指定使用哪一个:

s deploy -a agentrun-deploy

或者使用特定的配置文件:

s deploy -t s.prod.yaml -a production

部署过程包含多个步骤:首先上传构建产物到云端存储,然后调用 AgentRun API 创建或更新 Agent Runtime,配置网络和权限,最后创建默认端点并等待实例就绪。整个过程通常需要几分钟,您可以在终端看到实时的进度信息。

如果遇到问题,可以添加 --debug 参数查看详细的 API 调用日志:

s deploy --debug

这会输出每个 API 请求的 URL、参数、响应等详细信息,帮助您诊断问题。

部署成功后,终端会显示完整的输出信息:

agent:
  id:           abc123-def456-ghi789
  arn:          acs:agentrun:cn-hangzhou:123456789:runtimes/my-agent-runtime
  name:         my-agent-runtime
  description:  My Agent Runtime
  status:       READY
  region:       cn-hangzhou
  
endpoints:
  - id:         ep-abc123
    name:       production
    url:        https://12345.agentrun-data.cn-hangzhou.aliyuncs.com/agent-runtimes/my-agent-runtime/endpoints/production/invocations

输出中最重要的信息是 endpoint URL,这是您的 Agent 在云端的访问地址。将 API 路径拼接到这个 URL 后面,即可调用云端 Agent。

验证部署结果

部署完成后,使用 curl 命令测试云端 Agent 是否正常工作:

ENDPOINT_URL="https://12345.agentrun-data.cn-hangzhou.aliyuncs.com/agent-runtimes/my-agent-runtime/endpoints/production/invocations"

curl ${ENDPOINT_URL}/openai/v1/chat/completions \
  -XPOST \
  -H "content-type: application/json" \
  -d '{"messages": [{"role": "user", "content": "通过代码查询现在是几点?"}], "stream":true}'

这个请求与本地测试时完全相同,只是 URL 指向了云端服务。如果返回了正确的响应,说明部署成功。此时您的 Agent 已经在 AgentRun 平台上运行,享受平台提供的弹性伸缩、负载均衡、监控告警等企业级能力。

云端 Agent 会根据请求量自动扩缩容。当没有请求时,实例会自动缩减为零,不产生任何费用。当请求到来时,平台会在毫秒级别启动实例处理请求。这种 Serverless 架构极大地降低了运维成本,让您能够专注于业务逻辑而非基础设施管理。

管理运行中的 Agent

部署成功只是开始,持续的运维和管理同样重要。AgentRun 提供了丰富的管理命令,帮助您监控 Agent 的运行状态、查看日志、调整配置等。

查看 Agent 详细信息

使用 info 命令查看 Agent Runtime 的完整配置:

s info

这个命令会输出 Agent 的所有属性,包括资源配置、网络设置、环境变量、端点列表等:

agent: 
  id:           1062cdd0-042e-407b-8a3f-234370c2c68c
  arn:          acs:agentrun:cn-hangzhou:1583208943291465:runtimes/my-agent-runtime
  name:         my-runtime
  description:  My Agent Runtime
  artifactType: Code
  status:       READY
  resources: 
    cpu:    1
    memory: 2048
    port:   9000
  timestamps: 
    createdAt:     2025-01-01T00:00:00.000000Z
    lastUpdatedAt: 2025-01-01T01:00:00.000000Z
  region:       cn-hangzhou
  endpoints: 
    - id:   ep-abc123
      name: production
      url:  https://12345.agentrun-data.cn-hangzhou.aliyuncs.com/...

status: READY 表示 Agent 处于就绪状态,可以正常处理请求。如果状态为其他值(如 CREATING、UPDATING、FAILED),说明 Agent 正在进行某项操作或遇到了问题。

查询和分析日志

日志是诊断问题和了解 Agent 行为的重要工具。使用 logs 命令可以查询各种维度的日志:

# 查看最近的日志
s logs

# 实时监控日志流
s logs --tail

# 指定时间范围查询
s logs --start-time "2024-01-01 00:00:00" --end-time "2024-01-01 23:59:59"

# 根据请求 ID 查询完整调用链路
s logs --request-id 1-63f9c123-xxxx

# 根据实例 ID 查询特定实例的日志
s logs --instance-id c-63f9c123-xxxx

# 搜索包含特定关键词的日志
s logs --search "error"

# 只查看失败的请求
s logs --type fail

# 高亮显示匹配的文本
s logs --search "error" --match "error"

--tail 模式特别适合实时监控,它会持续输出新产生的日志,类似于 Unix 的 tail -f 命令。当您需要观察 Agent 对特定请求的响应时,这个模式非常有用。

日志内容包含了请求的完整上下文:用户输入、Agent 的推理过程、工具调用参数和结果、最终的响应内容、执行时间等。通过分析日志,您可以了解 Agent 的决策逻辑是否符合预期,发现性能瓶颈,定位错误原因。

更新 Agent 配置

当您修改了代码或配置后,需要重新部署才能让更改生效。AgentRun 支持热更新,部署过程中不会中断服务:

s build
s deploy

平台会创建新版本的实例,待新实例就绪后再将流量切换过去,然后销毁旧实例。整个过程对用户透明,不会造成服务中断。

如果只是修改了某些配置参数而没有改动代码,可以直接部署而无需重新构建:

s deploy

Serverless Devs 会智能判断哪些部分发生了变化,只更新必要的资源,从而加快部署速度。

删除 Agent Runtime

如果不再需要某个 Agent,可以使用 remove 命令删除:

s remove

系统会要求确认操作,因为删除是不可逆的。如果确定要删除,输入 y 确认。也可以使用 -y 参数跳过确认:

s remove -y

删除操作会清理 Agent Runtime 及其所有关联资源,包括端点、实例、配置等。但不会删除您在控制台创建的模型和沙箱资源,这些资源可能被其他 Agent 使用。

版本管理和灰度发布

在生产环境中,直接用新代码替换旧代码是有风险的。如果新版本存在 bug,可能会影响所有用户。AgentRun 提供了版本管理和灰度发布机制,让您能够安全地推出新功能。

理解版本系统

AgentRun 的版本系统将每次部署产生的 Agent 配置保存为一个不可变的版本。版本用整数标识,从 1 开始递增。此外还有一个特殊的 LATEST 版本,始终指向最新的部署。

当您执行 s deploy 时,如果代码或配置发生了变化,系统会自动创建新版本。您可以将某个稳定的版本发布为正式版本,并通过端点将流量路由到特定版本。

版本的不可变性是其核心优势。一旦创建,版本的内容永远不会改变,这保证了版本的可追溯性。如果新版本出现问题,可以立即切换回旧版本,实现快速回滚。

发布正式版本

通过 version publish 命令将当前部署发布为正式版本:

s version publish --description "Production release v1.0"

描述信息应该清晰地说明这个版本的主要变更和特性,方便日后查询。发布成功后,系统会为这个版本分配一个编号,例如版本 1、版本 2 等。

查看所有已发布的版本:

s version list

输出会显示每个版本的编号、发布时间、描述信息等。通过这些信息,您可以了解 Agent 的演进历史,在需要时快速定位特定版本。

使用端点管理流量

端点是 Agent 的访问入口,每个端点可以指向特定的版本。通过配置多个端点并设置流量权重,可以实现灰度发布。

在 s.yaml 中配置端点:

agent:
  endpoints:
    - name: production
      version: "1"
      description: "稳定版本"
    
    - name: canary
      version: "2"
      description: "灰度版本"
      weight: 0.2

这个配置创建了两个端点:production 端点指向版本 1,接收 80% 的流量;canary 端点指向版本 2,接收 20% 的流量。通过逐步增加 canary 的权重,可以平滑地将流量迁移到新版本。

部署配置后,端点会立即生效:

s deploy

您也可以通过命令行动态调整端点配置:

# 创建或更新端点,指向特定版本
s endpoint publish --endpoint-name prod-v2 --target-version 2 --description "Production v2"

# 调整灰度比例
s endpoint publish --endpoint-name canary --target-version 2 --weight 0.5

查看所有端点的配置:

s endpoint list

查看特定端点的详细信息:

s endpoint get --endpoint-name production

灰度发布完整流程

让我们通过一个完整的案例来理解灰度发布的最佳实践。假设您开发了一个新特性,需要在不影响现有用户的前提下逐步推广。

第一步是部署新代码并发布为正式版本:

# 修改代码后构建和部署
s build
s deploy

# 发布为版本 2
s version publish --description "Added new feature X"

第二步是创建灰度端点,将 10% 的流量导入新版本:

s endpoint publish --endpoint-name canary --target-version 2 --weight 0.1 --description "Canary 10%"

此时 production 端点仍然指向版本 1,大部分用户不受影响。只有 10% 的流量会体验到新特性,您可以通过监控日志和指标来验证新版本的稳定性。

第三步是观察一段时间后逐步增加流量。如果新版本运行正常,将灰度比例提高到 50%:

s endpoint publish --endpoint-name canary --target-version 2 --weight 0.5

继续观察,如果没有问题,最终将 production 端点切换到新版本:

s endpoint publish --endpoint-name production --target-version 2

现在所有流量都已迁移到版本 2,灰度发布完成。如果在任何阶段发现问题,可以立即将端点切回旧版本,实现快速回滚:

s endpoint publish --endpoint-name production --target-version 1

这个流程既保证了新功能的充分验证,又最大限度降低了故障影响范围,是生产环境推荐的发布策略。

实例管理和诊断

在某些情况下,您需要深入到运行实例内部进行诊断。AgentRun 提供了实例管理命令,允许您查看实例状态、执行调试命令等。

查看运行实例列表

使用 instance list 命令查看当前运行的所有实例:

s instance list

输出会显示每个实例的 ID、状态、创建时间等信息。实例的生命周期由平台自动管理,当有请求需要处理时创建实例,空闲一段时间后自动回收。

在实例中执行命令

instance exec 命令允许您在运行的实例中执行任意命令,这对于调试问题非常有用:

# 执行单个命令
s instance exec --instance-id c-xxxx --cmd "ls -lh"

# 查看进程列表
s instance exec --instance-id c-xxxx --cmd "ps aux"

# 查看环境变量
s instance exec --instance-id c-xxxx --cmd "env"

# 读取文件内容
s instance exec --instance-id c-xxxx --cmd "cat /app/app.py"

您还可以打开交互式 Shell,就像 SSH 登录到实例一样:

s instance exec --instance-id c-xxxx

这会启动一个交互式终端,您可以执行多个命令、查看文件、检查进程状态等。退出时输入 exit 即可。

如果需要在特定目录执行命令,使用 --workdir 参数:

s instance exec --instance-id c-xxxx --workdir /app --cmd "pwd"

需要注意的是,对实例的修改不会持久化。实例重启后会恢复到部署时的状态。如果需要永久性修改,应该修改代码并重新部署。

并发控制和性能优化

AgentRun 的弹性伸缩机制可以根据负载自动调整实例数量,但有时您需要更精细的控制。并发配置允许您设置预留并发和最大并发,优化成本和性能的平衡。

理解并发模型

AgentRun 的并发控制有两个维度。实例级并发(instanceConcurrency)决定了单个实例能同时处理多少个请求。账户级并发则决定了您的 Agent 总共能启动多少个实例。

默认情况下,实例级并发为 10,这适合大多数场景。如果您的 Agent 逻辑非常轻量,可以提高这个值以减少实例数量,降低冷启动的影响。如果 Agent 需要大量计算资源,则应该降低这个值,避免实例过载。

账户级并发包括预留并发和最大并发。预留并发是平台保证始终可用的实例数量,即使在高峰期也能立即响应请求。最大并发则是实例数量的上限,防止失控的流量耗尽您的配额。

配置并发参数

在 s.yaml 中设置实例级并发:

agent:
  instanceConcurrency: 20  # 单实例可同时处理 20 个请求

设置预留并发通过命令行完成:

s concurrency put --reserved-concurrency 10

这个命令预留了 10 个并发额度,平台会保证始终有足够的实例来处理这个并发量。预留并发适合有稳定基线流量的应用,可以消除冷启动延迟。

查看当前的并发配置:

s concurrency get

移除并发配置,恢复为完全弹性模式:

s concurrency remove

系统会要求确认操作,因为移除预留并发后,实例可能会被回收,导致后续请求遇到冷启动。

生产环境最佳实践

在实际项目中积累的经验教训往往比文档更有价值。以下是一些经过验证的最佳实践,可以帮助您避免常见的陷阱,构建更稳定、更安全的 Agent 应用。

项目组织建议

良好的项目结构是可维护性的基础。推荐的目录组织如下:

my-agentrun-project/
├── .git/
├── .gitignore
├── README.md
├── s.yaml              # 默认配置
├── s.dev.yaml         # 开发环境配置
├── s.prod.yaml        # 生产环境配置
└── code/
    ├── app.py
    ├── requirements.txt
    ├── .env           # 本地环境变量(不提交到 Git)
    ├── .env.example   # 环境变量模板
    ├── agent/         # Agent 业务逻辑
    │   ├── __init__.py
    │   ├── handler.py
    │   └── tools.py
    └── utils/         # 通用工具函数
        ├── __init__.py
        └── logger.py

将业务逻辑分散到多个模块中,每个模块负责特定的功能。app.py 作为入口文件应该保持简洁,主要负责初始化和启动服务。具体的 Agent 逻辑放在 agent 目录中,工具函数放在 utils 目录中。

创建 .env.example 文件作为环境变量模板,列出所有需要的配置项但不包含实际值:

AGENTRUN_ACCESS_KEY_ID=
AGENTRUN_ACCESS_KEY_SECRET=
AGENTRUN_ACCOUNT_ID=
AGENTRUN_REGION=cn-hangzhou

团队成员可以复制这个文件为 .env 并填入自己的凭证。这种方式既方便了新成员上手,又避免了泄露敏感信息。

Git 忽略配置

.gitignore 文件应该排除所有不应该提交到版本控制的内容:

# 环境变量和敏感信息
.env
.env.local
*.key
*.pem

# Serverless Devs 构建产物
.s/
.serverless/

# Python 运行时文件
__pycache__/
*.py[cod]
*$py.class
*.so
venv/
env/
ENV/

# IDE 和编辑器文件
.idea/
.vscode/
.DS_Store
*.swp
*.swo

# 日志文件
*.log
logs/

确保在项目初始化时就创建这个文件,避免意外提交敏感信息。

环境隔离策略

为开发、测试、生产环境创建完全独立的配置,包括:

• 不同的 Agent Runtime 名称(如 agent-dev、agent-prod)
• 不同的模型和沙箱资源
• 不同的资源配置(开发环境用小规格,生产环境用大规格)
• 不同的网络配置(开发环境可以公网访问,生产环境使用 VPC)
• 不同的日志级别(开发环境用 DEBUG,生产环境用 INFO)

理想情况下,为不同环境使用不同的阿里云账号或 RAM 用户,实现权限和资源的完全隔离。这样即使开发环境出现问题,也不会影响生产环境。

安全加固建议

安全性应该贯穿开发的每个环节。以下是关键的安全实践:

首先,绝对不要在代码中硬编码密钥或密码。所有敏感信息都应该通过环境变量传递。使用 .gitignore 确保 .env 文件不会被提交到 Git。

其次,为不同环境使用不同的 API Key 和访问凭证。这样即使某个环境的凭证泄露,也不会影响其他环境。定期轮换凭证也是好习惯,建议至少每季度更换一次。

第三,生产环境应该启用 VPC 网络隔离。将 Agent 实例部署在虚拟私有网络中,只暴露必要的端点,所有内网资源(如数据库)都不应该直接暴露在公网上。

第四,配置 RAM 角色时遵循最小权限原则。只授予 Agent 必需的权限,不要为了方便而使用管理员权限。定期审计角色权限,移除不再需要的策略。

第五,启用日志服务并配置日志分析和告警。及时发现异常访问模式,例如频繁的失败请求可能意味着有人在尝试攻击。

监控和告警策略

可观测性是生产系统的生命线。配置全面的监控指标和告警规则,在问题影响用户之前发现并解决它们。

关键的监控指标包括:

• 请求量和 QPS:了解流量模式,为扩容决策提供依据
• 响应时间(P50、P90、P99):识别性能问题
• 错误率:及时发现功能故障
• 实例数量和并发度:评估资源利用效率
• 模型调用延迟和成本:优化模型使用策略

在 AgentRun 控制台或 SLS 中配置告警规则。例如,当错误率超过 5% 时发送告警,当 P99 响应时间超过 30 秒时发送告警,当单小时成本超过阈值时发送告警等。

告警应该分级处理。紧急告警(如服务完全不可用)应该立即通知值班人员,可以通过短信或电话。普通告警(如某个端点的错误率略有上升)可以通过邮件或钉钉通知,在工作时间处理即可。

持续监控日志,寻找优化机会。例如,如果发现某个工具的调用延迟很高,可以考虑优化实现或缓存结果;如果发现用户经常问同类问题,可以针对性地优化提示词或添加专门的处理逻辑。

常见问题和解决方案

在实际使用中,您可能会遇到一些常见的问题。以下是这些问题的诊断方法和解决方案。

问题:部署时报错 "agent configuration is required"

这个错误表示配置文件格式有问题。检查 s.yaml 文件,确保 props 下有 agent 字段,并且缩进正确。YAML 对缩进非常敏感,使用空格而非制表符,每级缩进两个空格。

问题:本地测试正常,部署后无法访问

这种情况通常有几个原因。首先检查端口配置是否一致,确保 s.yaml 中的 port 与代码中 AgentRunServer 监听的端口相同。其次检查环境变量,本地通过 .env 文件加载的变量在云端需要配置在 s.yaml 的 environmentVariables 中。第三检查 RAM 角色权限,确保角色有访问模型和沙箱的权限。最后查看日志,通过 s logs --type fail 查看失败请求的详细信息。

问题:如何回滚到之前的版本

如果新版本出现问题,通过端点切换快速回滚。首先查看版本列表 s version list,找到稳定版本的编号,然后更新端点指向该版本 s endpoint publish --endpoint-name production --target-version 1。切换会立即生效,新的请求会路由到旧版本。

问题:构建失败,提示 "Docker is not running"

这表示本地 Docker 服务未启动。运行 docker ps 测试 Docker 是否正常。如果提示连接错误,启动 Docker Desktop(Mac/Windows)或 Docker 守护进程(Linux)。确认 Docker 运行后重新执行 s build。

问题:如何查看 Agent 运行时使用的环境变量

环境变量通过 s.yaml 的 environmentVariables 配置注入到实例中。要查看实例中的实际值,使用实例执行命令:s instance list 获取实例 ID,然后 s instance exec --instance-id c-xxxx --cmd "env | grep AGENTRUN" 查看所有 AGENTRUN 相关的环境变量。

问题:实例频繁冷启动,如何优化

冷启动是 Serverless 架构的常见挑战。优化方法包括:配置预留并发保持实例常驻,优化代码减少启动时间(例如延迟加载大型依赖),使用更轻量的基础镜像,或者通过定时任务定期发送请求保持实例温暖。根据业务特点选择合适的策略。

问题:日志查询很慢或查不到

如果配置了 SLS 日志服务,日志可能需要几秒钟才能被采集和索引。查询历史日志时,尽量缩小时间范围,使用 --start-time 和 --end-time 参数。如果通过 --request-id 查询,确保 ID 完全正确。如果仍然查不到,检查日志配置是否正确,role 是否有写入 SLS 的权限。

至此,您已经掌握了 AgentRun 应用开发的完整流程,从环境搭建到本地开发,从云端部署到生产运维。这些知识和实践将帮助您构建稳定、高效、安全的生产级 Agent 应用。随着对平台的深入使用,您会发现更多优化和定制的机会,不断提升 Agent 的能力和用户体验。