创建 Alephant 智能体

Alephant 是面向生产级 AI 智能体和工作流的智能体金融网关。它为智能体和工作流提供受治理的身份、策略层、运行追踪、成本归因，以及通过付费端点实现变现的路径。

在 Alephant 中，创建何种智能体取决于您要注册的对象：

• AI Agent 是通过 Alephant Gateway 使用 LLM 模型的应用、服务或自主智能体。
• Workflow Agent 是 Alephant 可以调用并在之后通过付费端点暴露的外部工作流或服务运行时，例如 n8n 工作流、Hermes 服务或 HTTPS 后端。

核心思路很简单：

AI Agent
Application, service, or autonomous agent
-> Alephant Virtual Key authentication
-> Alephant Gateway
-> Policy
-> LLM provider
-> Alephant logs, cost, and run attribution

Workflow Agent
Buyer, application, or another agent
-> Alephant paid endpoint or internal Agent invocation
-> Alephant Workflow Agent
-> Runtime connector
-> External workflow or service endpoint
-> Workflow execution
-> Stable JSON result
-> Alephant logs, policy, payment, revenue, and margin attribution

本页说明两种智能体类型，并展示如何为您的使用场景创建合适的一种。

视频演示

观看如何在 Alephant 中创建 AI 智能体和工作流智能体。

Open the Loom walkthrough

准备内容

创建智能体前，请确保已具备：

• Alephant 工作区。
• 想要创建的智能体类型：AI Agent 或 Workflow Agent。

对于 Gateway Access，请准备：

• 已在 Alephant 配置的模型访问条目，例如 OpenRouter 或其他 BYO 提供商密钥。
• 想使用的智能体策略。之后可在 Agent Detail -> Policy 中更改默认策略。

对于 Workflow Agent，还请准备：

• 运行时类型：n8n Workflow 或 Custom Webhook。
• Alephant 可以访问的 Webhook URL。
• HTTP 方法，例如 POST。
• 稳定的 JSON 请求与响应契约。

1. 了解两种智能体类型

填写配置字段前选择智能体类型。

当主要工作是将付费端点调用转发到现有工作流时，不要使用 AI Agent；应使用 Workflow Agent。

当主要工作是让应用使用 Virtual Key 调用模型时，不要使用 Workflow Agent；应使用 AI Agent。

2. 创建 AI 智能体

为使用 AI 模型的应用、服务或自主智能体创建 AI Agent。

AI Agent 为应用在 Alephant 中提供独立的受治理身份。创建时，Alephant 会自动生成绑定到该智能体的 Virtual Key。应用应使用此 Virtual Key，而非原始提供商 API 密钥。

AI 智能体配置示例：

智能体名称应描述产生流量的身份。若同一服务同时具有预发布和生产部署，请创建独立的智能体或 Virtual Key，以保持日志和预算控制清晰。

接下来配置 Gateway Access。选择智能体应使用的提供商密钥和默认模型，然后设置预算与策略控制。

UI 中显示的 Gateway Access 字段：

3. 保存 AI 智能体 Virtual Key

创建 AI Agent 后，Alephant 会返回该智能体的 Virtual Key。

Virtual Key 是应用发送给 Alephant Gateway 的凭证：

vk-...

请将 Virtual Key 存储在密钥管理器或受保护的环境变量中。不要将其提交到仓库、粘贴到截图中或暴露给用户。

密钥关系：

应用应仅向 Alephant Gateway 发送 Virtual Key，而不应发送原始提供商密钥。

4. 通过 Alephant Gateway 发送 AI 智能体流量

使用 Alephant Gateway 基础 URL，并在 Authorization 请求头中传递 Virtual Key。

curl 调用示例：

$
curl https://ai.alephant.io/v1/chat/completions \
>
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "Alephant-Agent-Id: <your-agent-id>" \
>
  -H "Alephant-Run-Id: run_<your-run-id>" \
>
  -H "alephant-session-id: <your-session-id>" \
>
  -H "x-request-id: <your-request-id>" \
>
  -d '{
>
    "model": "openai/gpt-4o-mini",
>
    "messages": [
>
      {
>
        "role": "user",
>
        "content": "Summarize this support ticket and suggest the next action."
>
      }
>
    ]
>
  }'

TypeScript 示例：

1
import OpenAI from "openai";
2
3
const client = new OpenAI({
4
  baseURL: "https://ai.alephant.io/v1",
5
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
6
  defaultHeaders: {
7
    "Alephant-Agent-Id": "<your-agent-id>",
8
    "Alephant-Run-Id": "run_<your-run-id>",
9
    "alephant-session-id": "<your-session-id>",
10
  },
11
});
12
13
const response = await client.chat.completions.create({
14
  model: "openai/gpt-4o-mini",
15
  messages: [
16
    {
17
      role: "user",
18
      content: "Summarize this support ticket and suggest the next action.",
19
    },
20
  ],
21
});

5. 创建工作流智能体

当 Alephant 应代表并调用外部工作流或服务运行时时，创建 Workflow Agent。

示例包括：

• 具有生产 Webhook URL 的 n8n 工作流。
• 具有稳定 HTTP 工具端点的 Hermes 服务。
• 作为 API 暴露的数据富化工作流。
• 返回 JSON 的合规、评分或研究工作流。

创建 Workflow Agent 的流程分为四步：

Identity
-> Gateway Access
-> Runtime
-> Connect

在 Identity 中选择 Workflow Agent，再选择运行时类别。当前 UI 将 n8n Workflow 和 Custom Webhook 显示为运行时选项。

Workflow Agent 同样拥有 Gateway Access 设置。即使主要执行发生在外部工作流运行时，这也让 Alephant 可以通过提供商密钥路由模型访问、签发限定范围的凭证、要求运行追踪、应用策略并记录成本。

工作流智能体配置示例：

工作流智能体的名称和描述应说明买方或内部用户获得的能力。避免以内部脚本或实现细节为其命名。

在 Gateway Access 中，选择 Alephant 应为此智能体使用的提供商密钥和默认模型。继续前配置月度预算并审阅附加策略。

UI 中显示的 Gateway Access 字段：

在 Runtime 中配置外部工作流连接，并在完成前进行测试。

UI 中显示的工作流运行时字段：

6. 保护对工作流的直接访问

如果 Workflow Agent 调用外部运行时 URL，应保护该 URL，防止被直接绕过。

建议的控制措施：

若运行时 URL 可从公网访问，请在执行工作流前验证网关来源。

常见的签名请求头模式为：

X-Alephant-Timestamp
X-Alephant-Signature

请将签名密钥存储在密钥管理器或受保护的环境变量中，不要提交到仓库。

7. 附加智能体、运行、会话、请求和追踪上下文

当流量包含稳定标识符时，Alephant 的可观测性最强。

推荐用于网关模型流量的请求头：

Authorization: Bearer <virtual-key>
Alephant-Agent-Id: <your-agent-id>
Alephant-Run-Id: run_<your-run-id>
alephant-session-id: <your-session-id>
x-request-id: <your-request-id>

对于付费端点活动，请将 trace_id 与智能体和运行上下文结合使用。不要使用付款追踪 ID 替代 Run ID：

• Alephant-Run-Id 描述智能体或工作流任务。
• trace_id 关联付款、结算、执行、成本和收入记录。
• x-request-id 标识单个 HTTP 请求。

8. 测试与验证

针对智能体类型测试正确的路径。

测试 Gateway Access

使用智能体 Virtual Key 通过 Alephant Gateway 发送模型请求：

$
curl https://ai.alephant.io/v1/chat/completions \
>
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "Alephant-Agent-Id: <your-agent-id>" \
>
  -H "Alephant-Run-Id: run_test_001" \
>
  -d '{
>
    "model": "openai/gpt-4o-mini",
>
    "messages": [
>
      {
>
        "role": "user",
>
        "content": "Write one sentence confirming the gateway works."
>
      }
>
    ]
>
  }'

然后在 Alephant 中检查：

• 请求日志。
• 智能体归因。
• 所选提供商和模型。
• Token 用量和成本。
• 预算和速率限制行为。
• 策略决策。

测试工作流运行时

对于 Workflow Agent，先从受信任环境直接测试运行时：

$
curl -X POST "http://<your-domain-host>/webhook/news" \
>
  -H "Content-Type: application/json" \
>
  -d '{"topic":"finance","limit":3}'

然后测试调用该运行时的 Workflow Agent 或付费端点路径。请求应生成一个稳定的 JSON 响应，可追溯到智能体、Run ID 和请求日志。

生产清单

上线前，请确认：

• 已选择正确的智能体类型：AI Agent 或 Workflow Agent。
• 智能体名称和描述体现面向用户的能力。
• 环境设置正确，例如 development、staging 或 production。
• 已配置预算、速率限制和策略行为。
• 适用时，网关流量包含智能体、运行、会话和请求标识符。
• 工作流运行时 URL 受到密钥请求头、网关签名、IP 允许列表、私有网络或等效控制的保护。
• 工作流运行时会在高成本分支执行前验证请求 JSON。
• 日志不包含密钥、原始提供商密钥、回溯信息、本地路径或原始 stderr。

相关文档

• Quickstart Guide
• Agents & Routing
• Agent Gateway
• Provider & Virtual Keys
• Agent IDs And Run IDs
• Agent Run Tracing