快速开始 - PPIO 派欧云文档中心

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

概览

完整流程包含 4 个步骤：

✅ 集成 SDK - 在 Agent 代码中添加装饰器
✅ 配置 Agent - 使用 CLI 生成配置文件
✅ 部署 Agent - 一键部署到云端
✅ 调用 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: 部署失败怎么办？

检查依赖文件：确保 requirements.txt 包含所有依赖
查看详细日志：使用 --verbose 参数
检查网络连接：确保可以访问 PPIO Sandbox Domain（如 sandbox.ppio.cn）
验证 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: 本地测试正常，部署后调用失败？

可能原因：

环境变量未传递到沙箱实例
依赖包版本不一致
文件路径问题

解决方案：通过 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"
    }
)

​目录

​概览

​前置准备

​步骤 1: 集成 SDK 到 Agent

​1.1 创建 Agent 代码

​1.2 准备依赖文件

​1.3 本地测试

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

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

​3.1 部署命令

​3.2 查看部署结果

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

​方式 1: CLI 快速测试

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

​示例代码

​常见问题

​Q1: 如何获取 Agent ID？

​Q2: 部署失败怎么办？

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

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

目录

概览