> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 创建 Alephant 智能体

> 在 Alephant 中创建 AI 智能体和工作流智能体

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

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

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

核心思路很简单：

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

```text
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](https://www.loom.com/share/341b579577324087b320bd5b07975a16)

## 准备内容

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

* 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`       | 应用通过 Alephant Gateway 发送 LLM 流量。 | 绑定到智能体的 Virtual Key。           | Alephant Gateway 将模型调用路由至提供商。  |
| `Workflow Agent` | Alephant 应调用外部工作流、API 或服务运行时。    | Gateway Access 加上受治理的工作流运行时连接。 | n8n Workflow 或 Custom Webhook。 |

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

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

## 2. 创建 AI 智能体

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

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

![Create an AI Agent identity in Alephant](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/c85b4af09a6a856e0285b8ddb070e2a37ae362d521f6e97a439233b047f2dc11/docs/assets/agent/alephant-create-agent-identity.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260727%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260727T055349Z&X-Amz-Expires=604800&X-Amz-Signature=6c8c9f1cac2e63987fdf5e1c5f3666f43b1bc127e3157b2546891fa58027b368&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

AI 智能体配置示例：

| 字段    | 示例                           | 说明                                 |
| ----- | ---------------------------- | ---------------------------------- |
| 智能体类型 | `AI Agent`                   | 用于使用模型的应用或自主智能体。                   |
| 智能体名称 | `Finance Report Service`     | 为应用或能力命名。                          |
| 描述    | `抓取真实财经新闻并返回英文 Markdown 报告。` | 描述业务功能。                            |
| 环境    | `Production`                 | 正式发布前使用 `Staging` 或 `Development`。 |
| 框架    | `Custom`                     | 智能体可选的框架元数据。                       |

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

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

![Configure Gateway Access for an AI Agent](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/dbe7dd6ca6d3cf3cf1e390e85c81fc2f009231e0ed019197075dc3a6726b7946/docs/assets/agent/alephant-create-agent-gateway-access.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260727%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260727T055349Z&X-Amz-Expires=604800&X-Amz-Signature=c4d3fdaacb193bcc2a20c07d3a6c6272d91a46559b1d79ea5ef790b3239146cb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

UI 中显示的 Gateway Access 字段：

| 字段           | 示例                     | 说明                               |
| ------------ | ---------------------- | -------------------------------- |
| Model Access | `OpenRouter02`         | 用于模型路由的 BYO 提供商密钥。               |
| 默认模型         | `openrouter/auto`      | 智能体的默认模型。                        |
| 月度预算         | `$100 USD / month`     | 此智能体可选的预算上限。                     |
| 策略           | `Default Agent Policy` | 之后可在 Agent Detail -> Policy 中更改。 |

## 3. 保存 AI 智能体 Virtual Key

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

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

```text
vk-...
```

![Agent created credentials and connection details](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/3d519002aec1513d17697d163905658f5627a4877abb95c88d0ace1cda86aa97/docs/assets/agent/alephant-agent-created-connect.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260727%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260727T055349Z&X-Amz-Expires=604800&X-Amz-Signature=5d0361a5a636b88b77daffcfdc43ee0993d1f87914112ab40d26e35ab619338d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

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

密钥关系：

| 密钥                  | 所有者             | 可见方           | 用途                    |
| ------------------- | --------------- | ------------- | --------------------- |
| Provider Master Key | 您的工作区           | Alephant 安全存储 | 使 Alephant 能调用上游提供商。  |
| Virtual Key         | Alephant 智能体或成员 | 您的应用使用它       | 对网关流量进行认证，并将用量绑定到智能体。 |

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

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

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

curl 调用示例：

```bash
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 示例：

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai.alephant.io/v1",
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
  defaultHeaders: {
    "Alephant-Agent-Id": "<your-agent-id>",
    "Alephant-Run-Id": "run_<your-run-id>",
    "alephant-session-id": "<your-session-id>",
  },
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: "Summarize this support ticket and suggest the next action.",
    },
  ],
});
```

## 5. 创建工作流智能体

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

示例包括：

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

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

```text
Identity
-> Gateway Access
-> Runtime
-> Connect
```

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

![Create a Workflow Agent identity in Alephant](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/196e59673e04dae3d70e1107538e3a85235d12befacaecddf6b04a2e7ab4a354/docs/assets/agent/alephant-create-workflow-agent-identity.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260727%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260727T055349Z&X-Amz-Expires=604800&X-Amz-Signature=7ff595a4d29f4f5613e41aaa984240c2522f38db952e0b6a1ff7ef11ba5b0c5a&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

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

工作流智能体配置示例：

| 字段    | 示例                                | 说明                      |
| ----- | --------------------------------- | ----------------------- |
| 智能体类型 | `Workflow Agent`                  | 用于外部工作流或服务运行时。          |
| 运行时类型 | `n8n Workflow` 或 `Custom Webhook` | 选择 Identity 步骤显示的运行时选项。 |
| 智能体名称 | `Finance Report Service`          | 为工作流能力命名。               |
| 描述    | `抓取真实财经新闻并返回英文 Markdown 报告。`      | 描述面向用户的输出。              |
| 环境    | `Production`                      | 验证期间使用 `Staging`。       |

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

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

![Configure Gateway Access for a Workflow Agent](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/739ac641d66d0e4f0a1a745d74a33478a547f1e9e3c7053eec2bb1c837673d45/docs/assets/agent/alephant-create-workflow-agent-gateway-access.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260727%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260727T055349Z&X-Amz-Expires=604800&X-Amz-Signature=afcc51825c1df44cb248ccc273819908649d89293ed8e0389be8075be8b73ae0&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

UI 中显示的 Gateway Access 字段：

| 字段           | 示例                     | 说明                               |
| ------------ | ---------------------- | -------------------------------- |
| Model Access | `OpenRouter02`         | 用于模型路由的 BYO 提供商密钥。               |
| 默认模型         | `openrouter/auto`      | 智能体的默认模型。                        |
| 月度预算         | `$100 USD / month`     | 此智能体可选的预算上限。                     |
| 策略           | `Default Agent Policy` | 之后可在 Agent Detail -> Policy 中更改。 |

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

![Configure Workflow Runtime connection](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/508f45da9538de39bc49b4b71660d8ddeeda9651fc47adda760fbd8dcb35e761/docs/assets/agent/alephant-create-workflow-agent-runtime.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260727%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260727T055349Z&X-Amz-Expires=604800&X-Amz-Signature=7c9ed13be877e0da4a09383b8c17079cebd8444aa63be99d9837b496c795c370&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

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

| 字段          | 示例                                       | 说明                             |
| ----------- | ---------------------------------------- | ------------------------------ |
| Webhook URL | `http://<your-domain-host>/webhook/news` | Alephant 调用的 n8n 或 webhook 端点。 |
| 方法          | `POST`                                   | 与工作流端点匹配。                      |
| 身份验证        | `None` 或密钥请求头认证                          | 当运行时可从公网访问时，使用私有请求头或网关签名。      |
| 超时          | `30` 秒                                   | 让超时与工作流的预期延迟保持一致。              |
| 重试          | `0 retries`                              | 除非运行时具备幂等性，否则应从不重试开始。          |

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

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

建议的控制措施：

| 控制措施    | 建议                           | 原因             |
| ------- | ---------------------------- | -------------- |
| 密钥请求头   | 在 Alephant 与工作流运行时之间配置私有请求头。 | 防止随意的直接调用。     |
| 网关签名    | 可用时验证 Alephant 来源签名。         | 确认请求来自受信任网关。   |
| IP 允许列表 | 仅允许受信任的 Alephant 或代理出口。      | 缩小公网攻击面。       |
| 私有网络    | 支持时使用私有连接。                   | 避免将内部工作流暴露到公网。 |
| 请求验证    | 在高成本工作流步骤运行前验证 JSON。         | 防止格式错误或滥用调用。   |
| 超时      | 设置明确的运行时超时。                  | 防止智能体执行卡住。     |

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

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

```text
X-Alephant-Timestamp
X-Alephant-Signature
```

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

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

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

| 标识符        | 范围         | 创建方             | 何时复用                    |
| ---------- | ---------- | --------------- | ----------------------- |
| Agent ID   | 稳定的智能体身份   | Alephant        | 对同一智能体发出的每个请求复用。        |
| Run ID     | 一次任务执行     | 您的应用、服务或工作流     | 在同一任务的全部模型、工具或工作流调用中复用。 |
| Session ID | 对话或工作流会话   | 您的应用、服务或工作流     | 在一个会话内的相关运行中复用。         |
| Request ID | 一次 HTTP 请求 | 您的应用或 Alephant  | 每个请求使用一个唯一值。            |
| Trace ID   | 付款与执行对账    | Alephant 或您的追踪层 | 与付费端点活动和财务记录一同使用。       |

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

```text
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 发送模型请求：

```bash
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，先从受信任环境直接测试运行时：

```bash
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](/docs/overview/getting-started/quickstart-guide)
* [Agents & Routing](/docs/overview/core-concepts/agents-routing)
* [Agent Gateway](/docs/overview/core-concepts/agent-gateway)
* [Provider & Virtual Keys](/docs/overview/core-concepts/provider-virtual-keys)
* [Agent IDs And Run IDs](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds)
* [Agent Run Tracing](/docs/overview/core-concepts/agent-run-tracing)