Agent IDs And Run IDs

Agent IDs and Run IDs are the minimum context needed to turn model requests into agent run records.

Without these identifiers, Alephant can still log a gateway request against a Virtual Key. With them, Alephant can group requests into agent runs, connect those runs to sessions and workflows, and make cost, policy, and debugging views much more useful.

Identifier Model

Required Headers For Agent Runs

Send these headers with gateway requests when you want requests to appear under an agent run:

Older snippets may show X-Alephant-Agent. Prefer Alephant-Agent-Id in new integrations.

Naming Recommendations

Use IDs that are stable, searchable, and safe to store in logs.

Good examples:

Alephant-Agent-Id: agt_support_bot_8f3a
Alephant-Run-Id: run_ticket_8421_20260609_001
alephant-session-id: sess_customer_123_support_20260609
x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001

Avoid putting secrets, raw customer email addresses, access tokens, or regulated personal data in IDs or alephant-property-* headers.

Curl Example

$
curl https://ai.alephant.io/v1/chat/completions \
>
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
>
  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
>
  -H "alephant-session-id: sess_customer_123_support_20260609" \
>
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
>
  -H "alephant-property-workflow: support-triage" \
>
  -H "alephant-property-environment: production" \
>
  -d '{
>
    "model": "openai/gpt-4o-mini",
>
    "messages": [
>
      {
>
        "role": "user",
>
        "content": "Summarize this support ticket and suggest the next action."
>
      }
>
    ]
>
  }'

TypeScript Example

Use default headers when every request from a client instance belongs to the same agent run.

1
import OpenAI from "openai";
2
3
const agentId = "agt_support_bot_8f3a";
4
const runId = "run_ticket_8421_20260609_001";
5
const sessionId = "sess_customer_123_support_20260609";
6
7
const client = new OpenAI({
8
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
9
  baseURL: "https://ai.alephant.io/v1",
10
  defaultHeaders: {
11
    "Alephant-Agent-Id": agentId,
12
    "Alephant-Run-Id": runId,
13
    "alephant-session-id": sessionId,
14
    "alephant-property-workflow": "support-triage",
15
    "alephant-property-environment": "production",
16
  },
17
});
18
19
const response = await client.chat.completions.create({
20
  model: "openai/gpt-4o-mini",
21
  messages: [
22
    {
23
      role: "user",
24
      content: "Summarize this support ticket and suggest the next action.",
25
    },
26
  ],
27
});

If one process handles many runs, create a client per run or pass request-specific headers through the SDK request options your runtime supports.

Python Example

1
import os
2
from openai import OpenAI
3
4
agent_id = "agt_support_bot_8f3a"
5
run_id = "run_ticket_8421_20260609_001"
6
session_id = "sess_customer_123_support_20260609"
7
8
client = OpenAI(
9
    api_key=os.environ["ALEPHANT_VIRTUAL_KEY"],
10
    base_url="https://ai.alephant.io/v1",
11
    default_headers={
12
        "Alephant-Agent-Id": agent_id,
13
        "Alephant-Run-Id": run_id,
14
        "alephant-session-id": session_id,
15
        "alephant-property-workflow": "support-triage",
16
        "alephant-property-environment": "production",
17
    },
18
)
19
20
response = client.chat.completions.create(
21
    model="openai/gpt-4o-mini",
22
    messages=[
23
        {
24
            "role": "user",
25
            "content": "Summarize this support ticket and suggest the next action.",
26
        }
27
    ],
28
)

Multi-Step Run Pattern

Use the same Alephant-Run-Id for every model or tool call inside one task.

run_ticket_8421_20260609_001
  request 1: classify ticket
  request 2: retrieve policy summary
  request 3: draft customer reply
  request 4: score escalation risk

Use a new Alephant-Run-Id when the agent starts a different task, even if it belongs to the same user session.

sess_customer_123_support_20260609
  run_ticket_8421_20260609_001
  run_refund_check_8421_20260609_002
  run_followup_email_8421_20260609_003

n8n Workflow Pattern

For n8n workflows, use the n8n execution ID or a workflow-generated ID as the run ID.

Recommended mapping:

If you use the Alephant n8n community nodes, pass the returned requestId or requestLogId into later analytics steps. If you call the gateway through an n8n HTTP Request node, include the trace headers directly.

Paid Endpoint And Trace ID Notes

For paid endpoints, trace_id is used for financial-grade reconciliation across payment, settlement, execution, model cost, tool cost, and revenue records.

Do not replace Alephant-Run-Id with trace_id. Use them together:

• Alephant-Run-Id describes the agent task.
• trace_id links the financial and execution records for paid endpoint activity.
• x-request-id identifies an individual gateway request.

If paid endpoint activity has missing trace context, revenue and margin views may mark the call as incomplete or unattributed.

Verification Checklist

After sending requests:

1. Open Logs and search by x-request-id, run ID, or agent ID.
2. Open the Agent detail page and check the Runs view.
3. Confirm request cost, tokens, model, provider, and latency appear under the expected Agent.
4. If the run belongs to a workflow, confirm all related requests share the same Run ID.
5. If the workflow is monetized, confirm payment activity and cost records share trace context.

Related Pages

• Agent Run Tracing
• Agents & Routing
• Gateway Integration
• n8n Workflow Governance