跳转到主要内容
本文档将引导你在 5 分钟内 完成第一个 Agent 的开发、部署和调用。

​
目录

​
概览

完整流程包含 4 个步骤：
  1. ✅ 集成 SDK - 在 Agent 代码中添加装饰器
  2. ✅ 配置 Agent - 使用 CLI 生成配置文件
  3. ✅ 部署 Agent - 一键部署到云端
  4. ✅ 调用 Agent - 使用 SDK 或 CLI 调用 Agent

​
前置准备

确保已完成以下准备工作：
  • ✅ 已安装 Python 3.9+ 和 Node.js 20+
  • ✅ 已安装 Beta 版 Python SDK 和 Node.js CLI（参考 安装指南）
  • ✅ 已获取 PPIO API Key（从 控制台 获取）
  • ✅ 已安装 Docker.

​
步骤 1: 集成 SDK 到 Agent

​
1.1 创建 Agent 代码

在项目目录创建 app.py： 
from ppio_sandbox.agent_runtime import AgentRuntimeApp

# 创建 Agent Runtime 应用实例
app = AgentRuntimeApp()

# 使用装饰器定义 Agent 入口点
@app.entrypoint
def my_agent(request: dict) -> dict:
    """
    Agent 入口函数
    
    Args:
        request: 请求数据，通常包含 prompt 等字段
        
    Returns:
        响应数据字典
    """
    prompt = request.get("prompt", "")
    
    # Agent 业务逻辑
    # 这里可以调用 LLM、使用 Agent 框架、或任何自定义逻辑
    result = f"收到消息: {prompt}"
    
    return {"result": result}

# 本地运行入口
if __name__ == "__main__":
    app.run()

​
1.2 准备依赖文件

确保项目根目录有 requirements.txt 文件，包含必需的依赖： 
ppio-sandbox>=1.1.0b1
# 你的其他依赖...

​
1.3 本地测试

在部署前先本地测试： 
# 启动 Agent 服务
python app.py
在另一个终端测试： 
# 测试健康检查
curl http://localhost:8080/ping

# 测试 Agent 调用
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, Agent!"}'
预期输出： 健康检查应返回： 
{"status": "Healthy"}
Agent 调用应返回： 
{"result": "收到消息: Hello, Agent!"}

​
步骤 2: 使用 CLI 生成配置文件

使用 CLI 交互式配置 Agent： 
# 确保环境变量已配置
export PPIO_API_KEY=your-ppio-api-key

# 运行配置命令
npx ppio-sandbox-cli agent configure
根据 CLI 提示配置所需信息。完成后，CLI 会在项目目录下生成：
  • ppio.Dockerfile - Docker 构建文件
  • .dockerignore - Docker 忽略文件
  • .ppio-agent.yaml - Agent 配置文件

​
步骤 3: 一键部署到 PPIO 云端

⚠️ 重要：部署成功后会生成 agent_id，这是调用 Agent 的唯一标识，请务必记录。

​
3.1 部署命令

使用 CLI 一键部署： 
npx ppio-sandbox-cli agent launch

​
3.2 查看部署结果

部署成功后，.ppio-agent.yaml 文件会更新 status 字段： 
status:
  phase: deployed
  agent_id: agent-xxxx  # ⭐ 这是 Agent 的唯一标识
  last_deployed: '2025-10-23T10:35:00Z'
  build_id: build_xyz789
请记录 agent_id，后续调用时需要使用。

​
步骤 4: 通过 CLI 或 SDK 调用 Agent

​
方式 1: CLI 快速测试

使用 CLI 快速测试 Agent： 
npx ppio-sandbox-cli agent invoke "Hello, Agent!"
注意：CLI 会自动从 .ppio-agent.yaml 的 status.agent_id 字段读取 Agent ID。 预期输出： 
{"result": "收到消息: Hello, Agent!"}

​
方式 2: SDK 调用（生产环境推荐）

在后端服务中使用 SDK 调用 Agent：

​
示例代码

import asyncio
import json
import os
from ppio_sandbox.agent_runtime import AgentRuntimeClient
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 创建 Agent Runtime 客户端
client = AgentRuntimeClient(
    api_key=os.getenv("PPIO_API_KEY")
)

async def main():
    # 部署完成后从 .ppio-agent.yaml 的 status.agent_id 获取
    agent_id = "agent-xxxx"
    
    # 准备请求数据
    payload = json.dumps({
        "prompt": "Hello, Agent! Tell me something about AI."
    }).encode()
    
    # 调用 Agent
    print(f"🚀 Invoking agent: {agent_id}")
    response = await client.invoke_agent_runtime(
        agentId=agent_id,
        payload=payload,
        timeout=300
    )
    
    print(f"✅ Response: {response}")

if __name__ == "__main__":
    asyncio.run(main())

​
常见问题

​
Q1: 如何获取 Agent ID？

部署成功后，Agent ID 保存在 .ppio-agent.yaml 文件的 status.agent_id 字段： 
status:
  agent_id: agent-xxxxx  # 这里

​
Q2: 部署失败怎么办？

  1. 检查依赖文件：确保 requirements.txt 包含所有依赖
  2. 查看详细日志：使用 --verbose 参数
  3. 检查网络连接：确保可以访问 PPIO Sandbox Domain（如 sandbox.ppio.cn）
  4. 验证 API Key：确认 PPIO_API_KEY 正确
# 显示详细日志
npx ppio-sandbox-cli agent launch --verbose

​
Q3: 如何更新已部署的 Agent？

修改代码后重新部署即可： 
# 方式 1: 创建新版本（推荐）
npx ppio-sandbox-cli agent configure --agent-version 1.1.0
npx ppio-sandbox-cli agent launch

# 方式 2: 更新现有版本
npx ppio-sandbox-cli agent launch --update-existing

​
Q4: 本地测试正常，部署后调用失败？

可能原因：
  1. 环境变量未传递到沙箱实例
  2. 依赖包版本不一致
  3. 文件路径问题
解决方案： 通过 envVars 参数传递环境变量到沙箱实例： 
response = await client.invoke_agent_runtime(
    agentId=agent_id,
    payload=payload,
    envVars={
        "PPIO_API_KEY": os.getenv("PPIO_API_KEY"),
        "MODEL_NAME": "deepseek/deepseek-v3-0324"
    }
)