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

# 开发者平台概览

> 了解袋袋开发者平台的能力全景、认证方式与核心概念

袋袋开发者平台为你提供了一套完整的 API，让你能够将 AI 专家的能力集成到自己的应用中。无论你是想在后端服务中调用 AI Agent，还是构建一个面向终端用户的 AI 应用，袋袋平台都能满足你的需求。

## 能力全景

<CardGroup cols={2}>
  <Card title="Agents Run" icon="robot" href="/zh/developers/api/agents-run">
    调用袋袋专家（AI Agent），通过 SSE 流式获取回复。支持多轮对话、工具调用、记忆等高级能力。
  </Card>

  <Card title="Chat Completions" icon="comments" href="/zh/developers/api/chat-completions">
    OpenAI 兼容的对话补全接口。支持 `profy-*` 模型名直接调用专家，OpenAI SDK 零改动接入。
  </Card>

  <Card title="Events" icon="bolt" href="/zh/developers/api/events">
    上报自定义计费事件，用于 App 的按次计费场景。支持幂等性保障，防止重复扣费。
  </Card>

  <Card title="Models" icon="list" href="/zh/developers/api/models">
    获取平台可用模型列表及其能力信息，帮助你选择合适的模型。
  </Card>

  <Card title="Meters" icon="gauge" href="/zh/developers/api/meters">
    查询 App 的计费计量器配置，了解事件对应的扣费规则。
  </Card>
</CardGroup>

## 两种认证方式

袋袋平台提供两种认证方式，适用于不同场景：

<Tabs>
  <Tab title="API Key">
    **适用场景**：服务端直接调用、脚本、后台任务

    * 以 `sk-pro-` 为前缀
    * 在请求头中通过 `Authorization: Bearer sk-pro-xxxx` 传递
    * 积分从**开发者自己的账户**扣除
    * 在 [Platform Console](https://platform.profy.cn) 创建和管理

    ```bash theme={null}
    curl -H "Authorization: Bearer sk-pro-xxxx" \
         https://api.profy.cn/v1/models
    ```
  </Tab>

  <Tab title="OAuth Bearer">
    **适用场景**：代表用户操作的 App

    * 标准 OAuth 2.0 Authorization Code 流程
    * Access Token 通过 `Authorization: Bearer <access_token>` 传递
    * 积分从**授权用户的账户**扣除
    * 支持 Token 刷新与吊销

    ```bash theme={null}
    curl -H "Authorization: Bearer eyJhbGciOi..." \
         https://api.profy.cn/v1/chat/completions
    ```
  </Tab>
</Tabs>

详细说明请参阅 [认证指南](/zh/developers/authentication)。

## 核心概念

### 专家（数字专家）

专家是袋袋平台的核心产品形态——一个具备人格、工具、记忆和技能的 AI Agent。通过 `/v1/agents/run` 端点，你可以以 API 方式调用任意已发布的专家。

### Expert-as-Model

通过 `/v1/chat/completions` 端点使用 `model="profy-<identifier>"` 格式的模型名，即可用标准 OpenAI SDK 调用袋袋专家。专家背后的完整 Agent 能力（人格、工具、记忆、技能）对开发者完全透明——你只需像调用 `gpt-4o` 一样调用它。这让袋袋创作者定义的垂直领域 AI Agent 可以无缝接入任何支持 OpenAI API 的工具链（LangChain、Cursor 等）。

### App（外部应用）

App 是通过 OAuth + Events API 接入袋袋身份与计费体系的外部应用。App 开发者可以利用袋袋的用户系统和积分计费，快速实现商业化。

### 计费模型

| 模型            | 说明                  | 典型场景             |
| ------------- | ------------------- | ---------------- |
| **METERED**   | 按 token 用量计费        | AI 对话、文本生成       |
| **PER\_USE**  | 按次计费（通过 Events API） | 自定义功能调用          |
| **ONE\_TIME** | 一次性买断               | 专家解锁、Static Site |

## 开发者控制台

[Platform Console](https://platform.profy.cn) 是你管理 API 接入的统一控制台：

* **API Keys**：创建、查看、吊销 API Key
* **Usage Stats**：查看调用量趋势和分布
* **Call Logs**：搜索和查看每一次 API 调用的详情
* **Playground**：在线测试 API（即将推出）

Platform Console 与主站 `app.profy.cn` 共享登录态——在主站登录后即可直接访问。

## SDK

袋袋提供 Python 和 TypeScript 两种官方 SDK，封装了认证、流式解析、错误处理等细节：

<CodeGroup>
  ```bash Python theme={null}
  pip install profy
  ```

  ```bash TypeScript theme={null}
  npm install @profy-ai/sdk
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  from profy import Profy

  async with Profy(api_key="sk-pro-...") as client:
      result = await client.agents.run("my-expert", "你好")
      print(result.text)
  ```

  ```typescript TypeScript theme={null}
  import { Profy } from "@profy-ai/sdk";

  const client = new Profy({ apiKey: "sk-pro-..." });
  const result = await client.agents.run("my-expert", "你好");
  console.log(result.text);
  ```
</CodeGroup>

## MCP Server

袋袋提供 MCP（Model Context Protocol）Server，可直接在 Cursor、Codex 等 IDE 中使用。通过 MCP，你无需离开编辑器即可完成专家创建、配置、发布和收益查看等全部流程。

详情参阅 [MCP Server 集成](/zh/developers/mcp-server)。

## 下一步

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/zh/developers/quickstart">
    5 分钟完成第一次 API 调用
  </Card>

  <Card title="认证指南" icon="lock" href="/zh/developers/authentication">
    了解 API Key 和 OAuth 的详细用法
  </Card>

  <Card title="API 参考" icon="code" href="/zh/developers/api/agents-run">
    浏览完整的 API 端点文档
  </Card>

  <Card title="构建 App" icon="grid-2" href="/zh/developers/app-development">
    学习如何构建一个袋袋 App
  </Card>
</CardGroup>