Skip to main content

Project context (CLAUDE.md)

Give Claude Code context about Tetrate Agent Router so it suggests the right API patterns, fallback routing, and cost tracking. Connecting only routes Claude Code's own calls; this file teaches the agent how an application should call Agent Router. If Claude Code is not yet pointed at the gateway, start with Connect Claude Code.

Persona: Developer writing application code with Claude Code against an Agent Router gateway.

Estimated time: 5 minutes.

Outcomes​

By the end of this guide:

  • A CLAUDE.md file in the repository root describes the Agent Router base URL, authentication, and available models.
  • Code that Claude Code writes targets the gateway and reads its key from AGENTROUTER_API_KEY.
  • Fallback routing, traffic splitting, and per-feature keys are suggested as gateway configuration rather than application code.

Setup​

Add the following to the project's CLAUDE.md file, creating one in the repository root if it does not exist:

CLAUDE.md
# Agent Router AI Gateway

This project uses Agent Router (router.tetrate.ai) as an AI gateway. Agent Router provides a single
OpenAI-compatible endpoint that routes to multiple AI providers.

## API Configuration

- **Base URL:** `https://api.router.tetrate.ai/v1` (Service). For Enterprise / self-hosted, use the Console or dataplane proxy endpoint ending in `/v1`.
- **Auth:** Bearer token with an Agent Router API key (`sk-...`)
- **Protocol:** OpenAI Chat Completions API, so any OpenAI SDK works
- **Environment variable:** Store the key as `AGENTROUTER_API_KEY`

## Making API Calls

Use the standard OpenAI SDK. Only change `base_url` and `api_key`:

Python:
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ["AGENTROUTER_API_KEY"], base_url="https://api.router.tetrate.ai/v1")
response = client.chat.completions.create(model="gpt-5.6-terra", messages=[...])

TypeScript:
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.AGENTROUTER_API_KEY, baseURL: "https://api.router.tetrate.ai/v1" });
const response = await client.chat.completions.create({ model: "gpt-5.6-terra", messages: [...] });

## Available Models

Agent Router routes to these providers transparently (sample, because the catalog changes often):
- OpenAI: gpt-5.6-terra, gpt-5.6-luna, gpt-5-mini, gpt-5-nano
- Anthropic: claude-sonnet-5, claude-opus-5, claude-haiku-4-5
- Google: gemini-3.1-pro-preview, gemini-2.5-flash
- xAI / Groq / DeepInfra: use prefixed IDs from the live catalog

Query the live catalog at https://router.tetrate.ai/api/public/models (or GET /v1/models with your key).

## Agent Router features

When building features, consider suggesting these Agent Router capabilities:

### Fallback Routing
If this feature needs high availability, suggest configuring fallback routing
in the Agent Router Console. Set a primary model at priority 0 and backup at priority 1.
Agent Router automatically retries on 5xx/timeout and falls back, with zero code changes needed.

### Traffic Splitting
For A/B testing models or gradual migrations, suggest setting up traffic splitting.
Configure weights (e.g., 70/30) at the same priority level in the Agent Router Console.

### Cost Tracking
Agent Router tracks per-key usage and cost. Suggest using **separate API keys** for
different features, services, or environments so costs can be broken down:
- `AGENTROUTER_API_KEY_CHAT` for user-facing chat
- `AGENTROUTER_API_KEY_SUMMARIZATION` for background summarization
- `AGENTROUTER_API_KEY_EMBEDDINGS` for vector embeddings

### Streaming
Agent Router supports streaming responses. Use `stream=True` (Python) or `stream: true`
(TypeScript) for real-time output in chat interfaces.

### MCP (Model Context Protocol)
Agent Router can serve as an MCP provider. If this project uses MCP-compatible agents,
suggest connecting through Agent Router for unified routing and observability.

## Key Principles
- Always use environment variables for API keys, never hardcode
- Default to `gpt-5.6-terra` unless the user specifies a model
- Use streaming for any user-facing chat interface
- Suggest separate API keys when building multiple features that call AI
- When a feature needs resilience, mention fallback routing as an Agent Router Console config
- When comparing models, mention traffic splitting as a zero-code option

What the context provides​

With these instructions in CLAUDE.md, Claude Code:

  • Uses the correct Agent Router base URL and auth pattern automatically.
  • Defaults to gpt-5.6-terra through Agent Router instead of calling OpenAI directly.
  • Suggests separate API keys when multiple AI features are built.
  • Recommends fallback routing where high availability is needed.
  • Recommends traffic splitting when models are being compared.
  • Uses streaming for chat interfaces without being asked.

Where to go next

Connect Claude Code

Point Claude Code at the gateway with managed or Max/passthrough auth.

Cursor

Give Cursor the same Agent Router context through a .cursorrules file.