Quickstart Integration

AgentRail acts as a transparent drop-in proxy. You can use your existing OpenAI SDK in Python or TypeScript — simply update base_url and pass an Idempotency-Key header.

Pilot Credentials

To connect to your pilot instance, ensure you have your credentials:

• Gateway URL: https://<your-pilot-id>.agentrail.workers.dev/v1
• Agent Token: AGENT_TOKEN (used by your agent to dispatch tasks)

---

1. Python Integration

Install the official OpenAI package:

pip install openai

Configure your client:

import os
import uuid
from openai import OpenAI

# 1. Point base_url to your AgentRail Edge Gateway
client = OpenAI(
    base_url="https://<your-pilot-id>.agentrail.workers.dev/v1",
    api_key=os.environ.get("AGENTRAIL_AGENT_TOKEN")
)

# 2. Attach an Idempotency-Key for exactly-once execution
task_id = f"task-{uuid.uuid4().hex[:12]}"

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "You are a financial research analyst."},
            {"role": "user", "content": "Analyze the fixed-price margin risks for software agencies."}
        ],
        extra_headers={
            "Idempotency-Key": task_id,
            "X-Agent-Tool": "openai-chat"
        }
    )
    print("Agent Result:", response.choices[0].message.content)

except Exception as error:
    # If the budget is exhausted, AgentRail returns HTTP 429 BUDGET_EXCEEDED
    print(f"Spend firewall blocked request: {error}")

---

2. TypeScript / Node.js Integration

Install the OpenAI npm package:

npm install openai

Route agent calls:

import OpenAI from 'openai';
import { randomUUID } from 'node:crypto';

const openai = new OpenAI({
  baseURL: 'https://<your-pilot-id>.agentrail.workers.dev/v1',
  apiKey: process.env.AGENTRAIL_AGENT_TOKEN,
});

async function runResearchTask(prompt: string) {
  const taskId = `task-${randomUUID().slice(0, 10)}`;

  try {
    const completion = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: prompt }],
    }, {
      headers: {
        'Idempotency-Key': taskId,
        'X-Agent-Tool': 'openai-chat',
      }
    });

    console.log('Result:', completion.choices[0]?.message.content);
  } catch (error: any) {
    if (error.status === 429) {
      console.warn('⚠️ Budget limit reached! Request Smart Top-Up from operator.');
    } else {
      console.error('Execution error:', error);
    }
  }
}

runResearchTask('Summarize regulatory requirements for autonomous AI agents.');

---

3. Raw cURL

curl -X POST "https://<your-pilot-id>.agentrail.workers.dev/v1/execute" \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN" \
  -H "Idempotency-Key: task-req-12345" \
  -H "X-Agent-Tool: openai-chat" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "messages": [{"role": "user", "content": "Provide a 3-bullet summary."}],
      "model": "gpt-4o-mini"
    },
    "acceptance": "json-object"
  }'