Choose Your Integration Path

Agumbe AI Gateway is designed to fit into different application architectures. You can start with a simple SDK call, use direct HTTP requests, or build a more controlled backend integration for production workloads.

This page helps you choose the right path.

Recommended path

For most production applications, call Agumbe AI Gateway from your backend service. Your frontend or client application should call your own backend. Your backend should call Agumbe using a Gateway API key. This keeps your API key private, gives you one place to add retries and logging, and lets you control which app, model, and guardrail policy are used for each request.

Use this path when:

• You are building a production application
• You need to keep credentials server-side
• You want consistent guardrails across user requests
• You want to attach internal metadata such as workspace, operation, or request ID
• You want better control over logging, error handling, and retries

Typical flow:

Client application → Your backend → Agumbe AI Gateway → Model provider

Example:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AGUMBE_API_KEY,
  baseURL: "https://api.agumbe.ai/api/v1/llm",
});

export async function summarizeTicket(ticketText: string) {
  const response = await client.chat.completions.create({
    model: "smart-default",
    messages: [
      {
        role: "system",
        content: "You summarize support tickets for an operations team.",
      },
      {
        role: "user",
        content: ticketText,
      },
    ],
    max_completion_tokens: 200,
    agumbe_guardrails_app_id: "app_support",
    agumbe_metadata: {
      source_service: "support-api",
      operation: "ticket_summary",
    },
  } as any);
  return response.choices[0]?.message?.content ?? "";
}

Path 1: SDK integration

Use an SDK integration when you want the fastest path from setup to a working request. Agumbe exposes a provider-compatible API shape, so you can use a familiar LLM SDK and point it to the Agumbe base URL.

Use this path when:

• You want to integrate quickly
• Your team already uses an SDK-style workflow
• You want minimal custom HTTP code
• You are testing locally or building a backend service

Example:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AGUMBE_API_KEY,
  baseURL: "https://api.agumbe.ai/api/v1/llm",
});

const response = await client.chat.completions.create({
  model: "smart-default",
  messages: [
    {
      role: "user",
      content: "Explain AI Gateways in one sentence.",
    },
  ],
  max_completion_tokens: 100,
});

console.log(response.choices[0]?.message?.content);

Path 2: Direct HTTP integration

Use direct HTTP when you want full control over request construction or you are integrating from a system where an SDK is not available.

Use this path when:

• You are integrating from any language or runtime
• You want simple cURL-based testing
• You need low-level control over headers, retries, or transport
• You are building your own client wrapper

Example:

curl https://api.agumbe.ai/api/v1/llm/chat/completions \
  -H "Authorization: Bearer $AGUMBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "smart-default",
    "messages": [
      {
        "role": "user",
        "content": "Explain AI Gateways in one sentence."
      }
    ],
    "max_completion_tokens": 100
  }'

Path 3: Tenant-scoped API key

Use a tenant-scoped API key when one backend service needs to call the gateway on behalf of multiple apps or workflows.

With this path, your request chooses the app guardrail policy by passing agumbe_guardrails_app_id.

Use this path when:

• One service handles multiple AI workflows
• You want to choose the app policy per request
• You have shared infrastructure calling the gateway for many product surfaces
• You want central routing with flexible app-level guardrails

Example:

{
  "model": "smart-default",
  "messages": [
    {
      "role": "user",
      "content": "Draft a safe support reply."
    }
  ],
  "agumbe_guardrails_app_id": "app_support"
}

Path 4: App-scoped API key

Use an app-scoped API key when a key should always use one app’s guardrail policy. With this path, you do not need to pass agumbe_guardrails_app_id. The gateway applies the bound app’s guardrails automatically.

Use this path when:

• A workload belongs to one app
• You want tighter credential boundaries
• You want staging, production, or sensitive workflows to have separate keys
• You want to avoid accidentally applying the wrong guardrail policy

Example:

{
  "model": "smart-default",
  "messages": [
    {
      "role": "user",
      "content": "Summarize this internal note."
    }
  ]
}

If an app-scoped key is used with a different app ID, the gateway rejects the request with app_mismatch.

Path 5: Console and playground

Use the Agumbe Console when you want to test prompts, models, credentials, and guardrails before writing or changing application code.

Use this path when:

• You are exploring supported models
• You want to test a guardrail policy
• You want to compare request behavior before deploying
• You want to inspect usage, latency, or errors from recent runs

The playground is best for experimentation. Production traffic should go through your backend or service layer.

How to choose

• Choose SDK integration if you want the fastest backend setup.
• Choose direct HTTP if you want language-neutral control.
• Choose a tenant-scoped key if one service needs to select different app policies per request.
• Choose an app-scoped key if the workload should always use one app policy.
• Choose the Console playground if you are testing prompts, models, credentials, or guardrails before production.

For most teams, the best starting point is a backend SDK integration with a Gateway API key, smart-default as the model alias, and app-level guardrails configured in the Console.