> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 概览

## 什么是 PPIO Agent Runtime？

PPIO Agent Runtime 是一个轻量级 AI Agent 运行时框架，让您能够 **快速、低成本地将 AI Agent 部署上线**。

无需关心基础设施配置、容器编排、服务暴露等复杂细节，只需专注于 Agent 的业务逻辑开发。

***

## 核心组件

PPIO Agent Runtime 包含在 PPIO 沙箱的 SDK 与命令行工具中：

| 组件                   | 功能                                              |
| -------------------- | ----------------------------------------------- |
| **PPIO Sandbox SDK** | 提供装饰器 API，将 Agent 包装为标准 HTTP 服务。并提供调用 Agent 的方法 |
| **PPIO Sandbox CLI** | 一键配置、部署 Agent 到 PPIO Agent 沙箱生态                 |

***

## 部署流程

完整的部署和使用流程分为三个步骤：

### Step 1: 开发和改造 Agent

在 Agent 代码中集成 SDK，添加装饰器：

```python theme={null}
from ppio_sandbox.agent_runtime import AgentRuntimeApp

app = AgentRuntimeApp()

@app.entrypoint
def my_agent(request: dict):
    # Agent 业务逻辑
    return {"result": "..."}
```

### Step 2: 配置和部署

使用 CLI 工具配置并部署到云端：

```bash theme={null}
# 配置 Agent
ppio-sandbox-cli agent configure

# 部署到云端
ppio-sandbox-cli agent launch
```

* 生成 `Dockerfile` 和 `.ppio-agent.yaml` 配置文件
* 构建沙箱模板并上传
* 生成 Agent ID（格式：`agent_<name>_v<version>`）

### Step 3: 调用 Agent

部署成功后，可以通过 CLI 或 SDK 调用：

**方式 1：使用 CLI 快速测试**

```bash theme={null}
ppio-sandbox-cli agent invoke "Hello, Agent!"
```

**方式 2：使用 SDK 在应用中调用**

```python theme={null}
import json
from ppio_sandbox.agent_runtime import AgentRuntimeClient

client = AgentRuntimeClient(api_key="your-api-key")

# 准备请求数据（需要先转为 JSON 字符串再编码为 bytes）
payload = json.dumps({"prompt": "Hello, Agent!"}).encode()

response = await client.invoke_agent_runtime(
    agentId="agent-xxxxx",
    payload=payload
)
```

**调用 Agent 的执行过程**：

* 从沙箱模板创建独立的沙箱实例
* 在隔离环境中执行 Agent
* 返回处理结果

***

## 核心优势

SDK:

* ✅ **最小改造**：仅需修改少量代码，使用装饰器包装即可
* ✅ **框架无关**：支持 LangChain、LangGraph、CrewAI 等所有 AI 框架
* ✅ **流式支持**：原生支持流式响应，适配 LLM 实时生成场景
* ✅ **健康检查**：内置健康检查端点，支持自定义健康状态

CLI:

* ✅ **智能检测**：自动检测项目结构、入口文件、依赖管理文件
* ✅ **自动构建**：自动生成 Dockerfile、项目配置
* ✅ **版本管理**：支持多版本并存，独立部署
* ✅ **快速测试**：内置调用命令，快速验证部署结果

运行时：

* ✅ **环境隔离**：每个沙箱实例独立运行，互不干扰
* ✅ **会话保持**：可对同一沙箱实例多次调用，支持多轮交互式 Agent
* ✅ **安全沙箱**：安全隔离的沙箱环境，受限的文件系统访问权限