> 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.

# Create Alephant Agents

> Create AI Agents and Workflow Agents in Alephant

Alephant is an Agentic Finance Gateway for production AI agents and workflows. It gives agents and workflows a governed identity, policy layer, run tracing, cost attribution, and a path to monetization through paid endpoints.

In Alephant, Agent creation depends on what you are registering:

* An **AI Agent** is an application, service, or autonomous agent that consumes LLM models through Alephant Gateway.
* A **Workflow Agent** is an external workflow or service runtime, such as an n8n workflow, Hermes service, or HTTPS backend, that Alephant can invoke and later expose through a paid endpoint.

The key idea is simple:

```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
```

This page explains both Agent types and shows how to create the right one for your use case.

## Video Walkthrough

Watch how to create both an AI Agent and a Workflow Agent in Alephant.

[Open the Loom walkthrough](https://www.loom.com/share/341b579577324087b320bd5b07975a16)

## What You Need

Before creating an Agent, make sure you have:

* An Alephant workspace.
* The Agent type you want to create: `AI Agent` or `Workflow Agent`.

For **Gateway Access**, prepare:

* A model access entry, such as an OpenRouter or other BYO provider key configured in Alephant.
* The Agent policy you want to use. The default policy can be changed later in **Agent Detail -> Policy**.

For a **Workflow Agent**, also prepare:

* The runtime type: `n8n Workflow` or `Custom Webhook`.
* A Webhook URL that Alephant can reach.
* The HTTP method, such as `POST`.
* A stable JSON request and response contract.

## 1. Understand The Two Agent Types

Choose the Agent type before filling in configuration fields.

| Agent Type       | Use it when                                                           | Primary output                                              | Typical runtime                                   |
| ---------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| `AI Agent`       | The application sends LLM traffic through Alephant Gateway.           | A Virtual Key bound to the Agent.                           | Alephant Gateway routes model calls to providers. |
| `Workflow Agent` | Alephant should invoke an external workflow, API, or service runtime. | Gateway Access plus a governed workflow runtime connection. | n8n Workflow or Custom Webhook.                   |

Do not use an AI Agent when the main job is to forward a paid endpoint call into an existing workflow. Use a Workflow Agent for that case.

Do not use a Workflow Agent when the main job is to let your application call models with a Virtual Key. Use an AI Agent for that case.

## 2. Create An AI Agent

Create an AI Agent for an application, service, or autonomous agent that consumes AI models.

An AI Agent gives the application its own governed identity in Alephant. On creation, Alephant automatically generates a Virtual Key bound to that Agent. The application uses that Virtual Key instead of a raw provider API key.

![Create an AI Agent identity in Alephant](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/c85b4af09a6a856e0285b8ddb070e2a37ae362d521f6e97a439233b047f2dc11/docs/assets/agent/alephant-create-agent-identity.png)

Example AI Agent configuration:

| Field       | Example                                                             | Notes                                                           |
| ----------- | ------------------------------------------------------------------- | --------------------------------------------------------------- |
| Agent Type  | `AI Agent`                                                          | Use this for model-consuming applications or autonomous agents. |
| Agent Name  | `Finance Report Service`                                            | Name the application or capability.                             |
| Description | `Fetches real finance news and returns an English Markdown report.` | Describe the business function.                                 |
| Environment | `Production`                                                        | Use `Staging` or `Development` before rollout.                  |
| Framework   | `Custom`                                                            | Optional framework metadata for the Agent.                      |

The Agent name should describe the identity that creates traffic. If one service has staging and production deployments, create separate Agents or Virtual Keys so logs and budget controls stay clear.

Next, configure Gateway Access. Choose the provider key and default model the Agent should use, then set budget and policy controls.

![Configure Gateway Access for an AI Agent](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/dbe7dd6ca6d3cf3cf1e390e85c81fc2f009231e0ed019197075dc3a6726b7946/docs/assets/agent/alephant-create-agent-gateway-access.png)

Gateway Access fields shown in the UI:

| Field          | Example                | Notes                                           |
| -------------- | ---------------------- | ----------------------------------------------- |
| Model Access   | `OpenRouter02`         | BYO provider key used for model routing.        |
| Default Model  | `openrouter/auto`      | Default model for the Agent.                    |
| Monthly Budget | `$100 USD / month`     | Optional budget limit for this Agent.           |
| Policy         | `Default Agent Policy` | Can be changed later in Agent Detail -> Policy. |

## 3. Save The AI Agent Virtual Key

After the AI Agent is created, Alephant returns a Virtual Key for the Agent.

The Virtual Key is the credential your application sends to Alephant Gateway:

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

![Agent created credentials and connection details](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/3d519002aec1513d17697d163905658f5627a4877abb95c88d0ace1cda86aa97/docs/assets/agent/alephant-agent-created-connect.png)

Store the Virtual Key in a secret manager or protected environment variable. Do not commit it to a repository, paste it into screenshots, or expose it to users.

Key relationship:

| Key                 | Who owns it              | Who sees it                 | What it does                                                |
| ------------------- | ------------------------ | --------------------------- | ----------------------------------------------------------- |
| Provider Master Key | Your workspace           | Alephant stores it securely | Lets Alephant call the upstream provider.                   |
| Virtual Key         | Alephant Agent or Member | Your application uses it    | Authenticates gateway traffic and binds usage to the Agent. |

The application should send only the Virtual Key to Alephant Gateway. It should not send the raw provider key.

## 4. Send AI Agent Traffic Through Alephant Gateway

Use the Alephant Gateway base URL and pass the Virtual Key in the `Authorization` header.

Example curl call:

```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 example:

```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. Create A Workflow Agent

Create a Workflow Agent when Alephant should represent and invoke an external workflow or service runtime.

Examples include:

* An n8n workflow with a production Webhook URL.
* A Hermes service with a stable HTTP tool endpoint.
* A data enrichment workflow exposed as an API.
* A compliance, scoring, or research workflow that returns JSON.

The Workflow Agent creation flow has four steps:

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

In **Identity**, choose `Workflow Agent`, then select the runtime family. The current UI shows `n8n Workflow` and `Custom Webhook` as runtime options.

![Create a Workflow Agent identity in Alephant](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/196e59673e04dae3d70e1107538e3a85235d12befacaecddf6b04a2e7ab4a354/docs/assets/agent/alephant-create-workflow-agent-identity.png)

A Workflow Agent still receives Gateway Access settings. This lets Alephant route model access through a provider key, issue scoped credentials, require run tracking, apply policy, and record cost even when the main execution happens in an external workflow runtime.

Example Workflow Agent configuration:

| Field        | Example                                                             | Notes                                                 |
| ------------ | ------------------------------------------------------------------- | ----------------------------------------------------- |
| Agent Type   | `Workflow Agent`                                                    | Use this for external workflow or service runtimes.   |
| Runtime Type | `n8n Workflow` or `Custom Webhook`                                  | Select the runtime option shown in the Identity step. |
| Agent Name   | `Finance Report Service`                                            | Name the workflow capability.                         |
| Description  | `Fetches real finance news and returns an English Markdown report.` | Describe the user-facing output.                      |
| Environment  | `Production`                                                        | Use `Staging` while validating.                       |

The Workflow Agent name and description should describe the capability buyers or internal users receive. Avoid naming it after internal scripts or implementation details.

In **Gateway Access**, choose the provider key and default model that Alephant should use for this Agent. Configure the monthly budget and review the attached policy before continuing.

![Configure Gateway Access for a Workflow Agent](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/739ac641d66d0e4f0a1a745d74a33478a547f1e9e3c7053eec2bb1c837673d45/docs/assets/agent/alephant-create-workflow-agent-gateway-access.png)

Gateway Access fields shown in the UI:

| Field          | Example                | Notes                                           |
| -------------- | ---------------------- | ----------------------------------------------- |
| Model Access   | `OpenRouter02`         | BYO provider key used for model routing.        |
| Default Model  | `openrouter/auto`      | Default model for the Agent.                    |
| Monthly Budget | `$100 USD / month`     | Optional budget limit for this Agent.           |
| Policy         | `Default Agent Policy` | Can be changed later in Agent Detail -> Policy. |

In **Runtime**, configure the external workflow connection and test it before finishing.

![Configure Workflow Runtime connection](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/508f45da9538de39bc49b4b71660d8ddeeda9651fc47adda760fbd8dcb35e761/docs/assets/agent/alephant-create-workflow-agent-runtime.png)

Workflow Runtime fields shown in the UI:

| Field          | Example                                  | Notes                                                                             |
| -------------- | ---------------------------------------- | --------------------------------------------------------------------------------- |
| Webhook URL    | `http://<your-domain-host>/webhook/news` | The n8n or webhook endpoint Alephant calls.                                       |
| Method         | `POST`                                   | Match the workflow endpoint.                                                      |
| Authentication | `None` or secret header authentication   | Use a private header or gateway signature when the runtime is publicly reachable. |
| Timeout        | `30` seconds                             | Keep the timeout aligned with the workflow's expected latency.                    |
| Retry          | `0 retries`                              | Start without retries unless the runtime is idempotent.                           |

## 6. Protect Direct Workflow Access

If the Workflow Agent calls an external runtime URL, protect that URL from direct bypass.

Recommended controls:

| Control            | Recommendation                                                        | Why it matters                                      |
| ------------------ | --------------------------------------------------------------------- | --------------------------------------------------- |
| Secret header      | Configure a private header between Alephant and the workflow runtime. | Prevents casual direct calls.                       |
| Gateway signature  | Verify Alephant-origin signatures when available.                     | Confirms the request came from the trusted gateway. |
| IP allowlist       | Allow only trusted Alephant or proxy egress.                          | Reduces public attack surface.                      |
| Private networking | Use private connectivity when supported.                              | Avoids exposing internal workflows publicly.        |
| Request validation | Validate JSON before expensive workflow steps run.                    | Prevents malformed or abusive calls.                |
| Timeout            | Set explicit runtime timeouts.                                        | Prevents stuck Agent executions.                    |

If the runtime URL is publicly reachable, verify gateway origin before executing the workflow.

A common signature-header pattern is:

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

Store signing secrets in a secret manager or protected environment variable. Do not commit them to the repository.

## 7. Attach Agent, Run, Session, Request, And Trace Context

Alephant observability is strongest when traffic includes stable identifiers.

| Identifier | Scope                                | Who creates it                         | When to reuse it                                             |
| ---------- | ------------------------------------ | -------------------------------------- | ------------------------------------------------------------ |
| Agent ID   | Stable Agent identity                | Alephant                               | Reuse for every request from the same Agent.                 |
| Run ID     | One task execution                   | Your application, service, or workflow | Reuse across all model, tool, or workflow calls in one task. |
| Session ID | Conversation or workflow session     | Your application, service, or workflow | Reuse across related runs in one session.                    |
| Request ID | One HTTP request                     | Your application or Alephant           | Use one unique value per request.                            |
| Trace ID   | Payment and execution reconciliation | Alephant or your tracing layer         | Use with paid endpoint activity and financial records.       |

Recommended headers for gateway model traffic:

```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>
```

For paid endpoint activity, use `trace_id` together with Agent and Run context. Do not replace the Run ID with a payment trace ID:

* `Alephant-Run-Id` describes the Agent or workflow task.
* `trace_id` links payment, settlement, execution, cost, and revenue records.
* `x-request-id` identifies an individual HTTP request.

## 8. Test And Verify

Test the correct path for the Agent type.

### Test Gateway Access

Send a model request through Alephant Gateway with the Agent Virtual Key:

```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."
      }
    ]
  }'
```

Then check Alephant for:

* Request log.
* Agent attribution.
* Provider and model selected.
* Token usage and cost.
* Budget and rate-limit behavior.
* Policy decisions.

### Test Workflow Runtime

For a Workflow Agent, first test the runtime directly from a trusted environment:

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

Then test the Workflow Agent or paid endpoint path that invokes that runtime. The request should produce one stable JSON response that can be traced back to the Agent, Run ID, and request log.

## Production Checklist

Before going live, confirm that:

* The correct Agent type was selected: AI Agent or Workflow Agent.
* The Agent name and description describe the user-facing capability.
* Environment is set correctly, such as development, staging, or production.
* Budgets, rate limits, and policy behavior are configured.
* Gateway traffic includes Agent, Run, Session, and Request identifiers where applicable.
* Workflow runtime URLs are protected by a secret header, gateway signature, IP allowlist, private network, or equivalent control.
* Workflow runtimes validate request JSON before expensive branches run.
* Logs do not contain secrets, raw provider keys, tracebacks, local paths, or raw stderr.

## Related Documentation

* [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)