---

---

xpander.ai 是一个用于快速构建、运行和部署可靠 AI 智能体的运行时与控制平面。您可以通过 Chat 立即使用您的智能体。您可以部署托管型智能体（无服务器）或嵌入式智能体（容器）。在 Workbench 中添加工具，然后在 xpander 云或您自己的 VPC/Kubernetes 集群中运行。每个智能体都配备有状态数据库、CI/CD 和日志记录功能，并提供完全的代码访问权限。它支持任何框架。

🧰 xpander.ai 平台概览

💬 Chat (chat.xpander.ai) — 通用型 AI 智能体，能够自动发现您的智能体并安排任务。它是所有人使用您的智能体和工具的入口门户（支持自定义域名和自托管）。

🧪 Workbench (app.xpander.ai) — 您用于管理任何智能体框架的控制平面。从 Starter Kit 模板开始，然后从菜单中添加工具：MCP 服务器、连接器、内置操作或自定义操作。

🏗️ AgentOS — 将任何框架的智能体部署到您自己的 VPC/Kubernetes 集群或 xpander 云中的生产运行时；包含可靠的作业调度器和长期运行任务的编排功能，以及状态数据库、日志、机密信息、可观性监控和 CI/CD。

🔌 连接器中心 — 可以根据 OpenAPI 规范生成并运行 MCP 服务器，也可以使用内置的 2,000 多种工具库。支持 OAuth 和 API 密钥，并可与 Claude、ChatGPT 等其他 MCP 客户端原生集成。

🛠️ AI 工具 — OCR、浏览器自动化、代码解释器、无服务器代码执行器、PDF/CSV 工具等。

🚀 开始使用

请在 https://app.xpander.ai 注册并登录。

您的账户包含一个预配置的“Starter Kit”智能体，配有少量工具和状态存储，用于保存会话并展示其功能。在 Workbench 中，您可以自定义系统提示、切换模型，或者下载完整的智能体代码进行修改和部署。

Workbench 截图

然后打开 Chat，网址为 https://chat.xpander.ai → 选择“Starter Kit”智能体，添加 MCP 工具，或让它执行任务。

这个统一的 Chat 是一个功能丰富的通用型智能体，可以在您部署的所有智能体之间安排任务。您在 Workbench 中添加的任何内容都会在这里自动显示。

示例：

🛳️ 构建更多智能体并部署到生产环境

🛠️ 托管型智能体（无服务器，约 2 分钟）

• app.xpander.ai → 新建智能体 → Starter Kit（或选择其他框架）
• 从菜单中添加工具：MCP 服务器、连接器、内置操作或自定义操作
• 点击“部署”→ 您将获得开箱即用的状态数据库、日志和 CI/CD 功能

🔧 嵌入式智能体（容器，约 3 分钟）

npm install -g xpander-cli && xpander login
mkdir hello-world && cd hello-world
xpander agent new --name "hello-world" --framework agno --folder .
python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
xpander dev   # 本地运行
xpander deploy && xpander logs

随时切换

• 先从托管开始。通过下载代码并重新部署，可以转换为嵌入式：

xpander agent init <agent-id>
xpander agent deploy

运行位置

• 无论是托管还是嵌入式，都可以在 xpander 云或您自己的 VPC/Kubernetes 集群中运行。

托管与嵌入式（快速对比）

• 托管：无服务器，无需基础设施，自动扩展；是内部工具和快速投产的最佳途径。
• 嵌入式：由您自己管理容器和依赖项；完全掌控框架和运行时；非常适合高级策略、私有包和 GPU 场景。

您还可以使用 xpander.ai 构建新的 MCP 服务器——一次构建，随处使用。

• 可以基于 OpenAPI 生成，也可以自行提供定义文件。
• 可以托管在 xpander 云或您自己的 VPC/Kubernetes 集群中。
• 可供智能体和其他任何 MCP 客户端（例如 Claude Desktop）使用。

🧩 支持任何框架：Agno、LangChain、PydanticAI、CrewAI——或者您自己的运行时。

🔗 如何使用您的智能体

所有智能体——无论是托管还是嵌入式——都可以通过 Chat、Webhook、REST API、SDK、A2A 和 MCP 协议立即使用。

1. 💬 Chat — chat.<yourdomain>（或 https://chat.xpander.ai）

2. 🌐 Webhook — 每个智能体都有独立的 HTTPS 端点

curl --location "https://webhook.xpander.ai?agent_id=$XPANDER_AGENT_ID" \
  --header 'X-api-key: $XPANDER_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"prompt":"总结第三季度管道风险"}'

3. 🔌 REST API — 统一的 HTTP 接口，可用于所有智能体（Agno、LangChain、PydanticAI、CrewAI、自定义框架）。

统一的控制平面位于 https://api.xpander.ai — 一套 API 适用于任何框架、任何语言。

curl --location "https://api.xpander.ai/v1/tasks/invoke" \
  --header 'x-api-key: $XPANDER_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"agent_id":"$XPANDER_AGENT_ID","prompt":"总结第三季度管道风险"}'

您可以通过标准 HTTP 管理智能体、调用任务（同步/异步/流式）、处理知识库以及访问工具包——一切尽在掌握。

完整 API 文档：https://docs.xpander.ai/api-reference/rest-api

4. 🧪 SDK

pip install "xpander-sdk[agno]"

# .env
XPANDER_API_KEY=你的xpander_api_key
XPANDER_ORGANIZATION_ID=你的org_id
XPANDER_AGENT_ID=你的agent_id

from xpander_sdk import Backend
from agno.agent import Agent

backend = Backend()  # 从 .env 中读取 XPANDER_* 变量
agent = Agent(**backend.get_args())  # 数据库、MCP 工具、系统提示词

agent.print_response("你能帮我什么？")

5. 🤝 A2A — 聊天或 SDK 中的代理间调用。只需一条命令即可跨代理安排任务。

6. 🧩 MCP — 将所有代理连接到 Claude Desktop、Cursor 以及任何 MCP 客户端。

通过模型上下文协议，直接在你的 IDE 中使用 xpander 代理：

{
  "mcpServers": {
    "xpander.ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.xpander.ai/mcp/",
        "--header",
        "x-api-key:YOUR_API_KEY"
      ]
    }
  }
}

可用的 MCP 工具：

• 列出代理 — 发现你组织中的所有代理
• 调用代理 — 执行任意代理任务
• 创建任务 — 将任务加入代理队列
• 获取任务 — 检索任务状态和结果
• 获取代理线程 — 访问对话历史
• 获取线程消息 — 检索特定线程的消息

MCP 端点：

• 标准：https://api.xpander.ai/mcp/
• 服务器发送事件 (SSE)：https://api.xpander.ai/mcp/sse

此外：受治理的连接器和 MCP 服务器（2,000 多种工具）可托管在 xpander 云或你的 VPC/Kubernetes 中。

🧑‍💻 自定义代理代码（可选）

容器化的代理包含由你控制的实际代码。一个处理器会监听来自控制平面的任务，并提供一个 Task 对象，以便你可以选择框架、工具和运行时行为。对于无服务器或无代码代理，则无需此步骤。

只需运行 xpander agent new 并按照向导操作即可。它会创建一个 xpander_handler.py 文件和一个 Dockerfile。

以下是一个已使用 Agno 配置好的 xpander_handler.py 示例。

from xpander_sdk import Task、on_task、Backend
from agno.agent import Agent

@on_task
async def handler(task: Task):
    backend = Backend(configuration=task.configuration)
    agent = Agent(**backend.get_args(task=task))
    return await agent.arun(message=task.to_message())

📚 示例

• 本地模板：02-agents/local-agent/ — 在本地运行代理，并使用 Ollama 提供私有 LLM
• DevOps 代理：02-agents/devops/ — 在云端运行代理，拥有 EKS 权限以排查日志
• 旅行代理：02-agents/travel-agent/ — 一个简单的旅行助手代理
• 数据代理：02-agents/data-agent/ — 使用 Streamlit 构建自定义前端（而非 xpander.ai 的聊天界面）的演示

文档与社区

• 文档：https://docs.xpander.ai
• API 参考：https://docs.xpander.ai/api-reference/07-sdk
• 加入我们的 Slack：https://xpander.ai/slack-community

许可证

• 开源 SDK 运行时：Apache 2.0
• 托管平台：商业版（提供免费层级）

↑ 回到顶部 ↑

xpander.ai 快速上手指南

xpander.ai 是一个用于构建、运行和部署可靠 AI Agent 的运行时与控制平面。它支持任意框架（如 Agno, LangChain, CrewAI 等），提供无服务器（Managed）和容器化（Embedded）两种部署模式，并内置数据库、CI/CD 和日志监控功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• 运行时依赖:
  • Python 3.8+ (用于开发 Embedded Agents)
  • Node.js 18+ (用于安装 CLI 工具)
  • Docker (仅在使用 Embedded/容器化模式时需要)
• 账号: 需拥有 xpander.ai 账号 (注册地址)

安装步骤

1. 安装命令行工具 (CLI)

xpander 提供了全局 CLI 工具用于管理 Agent 生命周期。

npm install -g xpander-cli

2. 登录账号

安装完成后，通过终端登录您的 xpander 账号：

xpander login

系统将在浏览器中打开登录页面，授权后自动完成终端登录。

3. 安装 Python SDK (可选)

如果您计划在本地代码中集成 xpander 功能，请安装 SDK：

pip install "xpander-sdk[agno]"

基本使用

您可以选择零代码快速启动（Managed Agents）或代码优先开发（Embedded Agents）。

方案 A：零代码快速启动 (Managed Agents)

适合快速验证想法或使用内置工具，无需编写代码。

1. 访问工作台: 登录 app.xpander.ai。
2. 创建 Agent: 点击 New Agent，选择 Starter Kit 模板（或指定框架）。
3. 配置工具: 在菜单中添加工具（支持 MCP 服务器、连接器、内置动作或自定义动作）。
4. 部署: 点击 Deploy。系统将自动为您分配状态数据库、日志系统和 CI/CD 流水线。
5. 使用: 访问 chat.xpander.ai，选择刚创建的 Agent 即可开始对话或调度任务。

方案 B：代码优先开发 (Embedded Agents)

适合需要完全控制运行时、依赖项或使用私有 GPU 的场景。

1. 初始化项目

使用 CLI 创建一个名为 "hello-world" 的新 Agent 项目（以 agno 框架为例）：

mkdir hello-world && cd hello-world
xpander agent new --name "hello-world" --framework agno --folder .

2. 配置本地环境

创建虚拟环境并安装依赖：

python3 -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
# .venv\Scripts\activate

pip install -r requirements.txt

3. 本地运行与调试

在本地启动 Agent 进行开发测试：

xpander dev

4. 部署到生产环境

将容器化 Agent 部署到 xpander 云或您自己的 VPC/Kubernetes：

xpander deploy

查看实时日志：

xpander logs

如何在代码中调用 Agent

部署完成后，您可以通过多种方式调用 Agent。以下是使用 Python SDK 调用的示例：

1. 配置环境变量 (在项目根目录创建 .env 文件)：

XPANDER_API_KEY=your_xpander_api_key
XPANDER_ORGANIZATION_ID=your_org_id
XPANDER_AGENT_ID=your_agent_id

2. 编写调用代码：

from xpander_sdk import Backend
from agno.agent import Agent

# 自动读取 .env 中的配置
backend = Backend()

# 初始化 Agent，自动注入数据库、MCP 工具和系统提示词
agent = Agent(**backend.get_args())

# 执行任务
agent.print_response("What can you help me with?")

进阶：通过 MCP 在 IDE 中使用

您可以将 xpander Agent 连接到 Claude Desktop、Cursor 等支持 MCP 的客户端。在客户端配置文件中添加：

{
  "mcpServers": {
    "xpander.ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.xpander.ai/mcp/",
        "--header",
        "x-api-key:YOUR_API_KEY"
      ]
    }
  }
}

现在，您可以在 IDE 中直接调用所有已部署的 xpander Agent 及其工具。