使用代码模式从创建到部署Agent应用-人工智能平台PAI-阿里云

LangStudio 代码模式允许使用 Python 代码构建 Agent 应用，支持在云上完成创建、调试到部署的全流程。本文将在5分钟内完成一个支持工具调用/Skills/流式输出的 Agent 应用的创建和部署。

步骤一：创建应用并绑定运行时

首先，您需要创建一个应用，并为其准备一个用于开发调试的运行时环境。

登录PAI 控制台，在页面上方选择目标地域，如华东1（杭州）。
在左侧导航栏选择模型应用 > 大模型应用开发（LangStudio），并进入目标工作空间。
在应用页签，单击新建应用，在下拉列表中选择代码模式。
在新建应用页面，配置以下参数：
- 新建方式：选择从模板新建，并选择LLM Basic 模板。
- 名称：为应用命名。例如，智能问答Agent。
- 选择运行时：运行时是执行和调试工作流所需的计算环境，是进行后续调试的必要步骤。
  - 已有运行时：从下拉列表中选择一个。
  - 无可用运行时：单击新建运行时，使用默认配置创建一个。运行时仅用于开发调试阶段，与最终部署的服务无关。
  一个运行时可以同时被多个应用使用。
- 工作路径：此路径（一个 OSS Bucket 路径）用于存放工作流的配置、日志和调试过程中产生的临时文件。选择运行时后，会自动加载运行时的工作路径。
- 描述（可选）：填写应用的用途说明。
单击确定。系统将自动跳转到开发页面。

步骤二：理解项目模板并配置环境变量

项目模板说明

LLM Basic 模板提供了一个基础的 Agent 项目结构，帮助您快速开始。

project/
├── agent.py          # 入口文件：定义 FastAPI app 和 API 接口
├── agent_loop.py     # 核心逻辑：处理 LLM 调用、工具执行循环
├── agui.py           # AG-UI Protocol 事件流转换
├── skills.py         # 技能系统：发现、加载和执行技能
├── skills/           # 技能目录
│   ├── get-current-time/
│   └── create-plan/
├── requirements.txt  # Python 依赖
├── .env              # 环境变量文件（需手动创建）
└── README.md         # 详细文档

agent.py 是默认的入口文件，必须提供一个全局的 FastAPI 对象，命名为 app。LangStudio服务会自动识别并加载 app 对象来启动服务。
可通过README.md了解模板示例，进行修改和扩展。

配置环境变量

项目使用阿里云百炼提供的模型服务，需通过环境变量提供API-KEY。

在项目根目录创建 .env 文件：

DASHSCOPE_API_KEY=your-api-key-here

运行时启动时会自动加载 .env 文件中的环境变量。

步骤三：调试 Agent

启动调试环境：在开发页面右上方单击运行按钮，系统将启动运行时环境并加载您的代码。启动成功后，页面右侧将弹出调试面板。

API调试

在API调试页签，可以直接测试应用的 API。

选择要测试的接口，如 POST /。
填写请求参数并发送。

示例请求：

{
  "question": "北京今天的天气如何？"
}

预期响应：

{
  "answer": "北京今天天气晴朗，气温在 10°C 到 20°C 之间。"
}

对话面板调试

平台提供了可视化的对话面板，支持多轮会话：

切换到对话页面。
直接输入问题进行对话
实时查看 Agent 的响应。

对话面板使用 AG-UI Protocol，需要服务支持 /ag-ui 接口。

查看链路追踪

无论使用哪种调试方式，平台都会自动记录链路追踪信息：

请求耗时：各阶段耗时统计
LLM 调用详情：模型参数、Token 用量
工具调用记录：调用的工具及返回结果
错误信息：出错时的详细堆栈

查看日志

当代码出现异常时，可在运行页面查看 Worker 日志进行问题排查。

步骤四：部署服务

完成开发和调试后，您可以将应用部署为稳定、可扩展的在线服务。

在开发页面右上角，单击部署。
在弹出的配置页面中，配置部署的资源、服务名称、VPC等信息。这本质上是将您的 FastAPI 应用打包成一个 PAI-EAS 在线服务。
重要
由于应用中阿里云百炼大模型服务需要通过公网访问，而 EAS 服务默认不具备公网访问能力。因此，在部署时，必须为服务配置一个可访问公网的 VPC 和交换机（通常需要关联 NAT 网关），否则服务将调用失败。参见EAS访问公网或内网资源。
在跳转的部署流程页面，检查部署内容符合预期后，单击提交部署。
等待部署完成后（此过程可能需要5-10分钟），单击右上角跳转到 EAS，进入 EAS 服务详情页。
在概览页签，单击基本信息区域的查看调用信息可获取访问地址和认证 Token。

普通请求示例：

# 请将<EAS_ENDPOINT> 和 <EAS_TOKEN> 替换为您的服务地址和认证Token
curl -X POST '<EAS_ENDPOINT>' \
  -H 'Authorization: Bearer <EAS_TOKEN>' \
  -H "Content-Type: application/json" \
  -d '{"question": "北京今天的天气如何？"}'

通过服务详情页提供的监控与链路追踪功能，可以实时查看服务的性能指标和所有请求的详细链路。

步骤五：自定义你的Agent

基于LLM-Basic模板，你可以自定义自己的Agent逻辑，下面介绍最常见的几种自定义方式。

1. 修改 Agent 人设 / 系统提示词

目的：定义 Agent 的角色、行为和响应风格。

编辑 agent.py 中的 to_messages() 方法：

def to_messages(self) -> list:
    return [
        {"role": "system", "content": "你是一个专业的旅行规划助手，回答简洁、可执行，并给出清单。"},
        {"role": "user", "content": self.question},
    ]

2. 添加自定义工具（Function Calling）

目的：让 Agent 具备调用外部 API 或执行特定代码逻辑的能力，例如查询天气、数据库检索等。

定义工具函数：在 agent.py 文件中，定义一个标准的 Python 函数。

函数名会作为工具名暴露给模型
参数类型标注会自动生成工具 schema
支持 async def 异步函数

# 在 agent.py 中添加工具函数
def geocode(city: str) -> str:
    """获取城市的地理坐标"""
    # 这里替换为实际的 API 调用
    return '{"lat": 39.9042, "lng": 116.4074}'

# 在 agent_loop 调用时传入工具列表
async for chunk in agent_loop(req.to_messages(), [get_weather, geocode]):
    ...

注册工具：在 agent.py 的 API 接口中，将您定义的工具函数列表传递给 agent_loop。

# 在 agent.py 的 FastAPI 路由中

@app.post("/")
async def query(req: QueryRequest) -> QueryResponse:
    # 将工具函数列表传入 agent_loop
    tools = [get_weather, geocode]
    async for chunk in agent_loop(req.to_messages(), tools=tools):
        # ...

3. 添加技能（Skills）

技能用于组织复杂的操作指令和脚本。

创建技能目录和文件：在 skills/ 目录下为您的新技能创建一个子目录，例如 my-skill。在该目录中，必须包含一个 SKILL.md 文件，用于向模型描述该技能的用途和使用方法。
```
skills/
  └── my-skill/
      ├── SKILL.md      # 必需：技能定义文件
      └── scripts/      # 可选：存放该技能要执行的脚本
          └── run.py
```

编写技能定义文件：SKILL.md 包含元数据和详细说明。示例如下：

---
name: my-skill
description: 当用户需要执行某个特定任务时使用该技能。
---

# My Skill

## 目标
用一句话描述技能要做什么。

## 使用说明
详细的操作指令...

Agent 会在系统提示词中看到可用技能列表，并通过内置工具 load_skill_file 和 execute_script 来使用技能。