Skip to main content

Agent Frameworks

Integration guides for connecting popular AI agent frameworks to Rivaro. Every framework that uses an OpenAI-compatible API works with Rivaro — you just change the base URL and add a detection key header.

How it works​

Rivaro is a transparent proxy. Your agent sends requests to localhost:8080 (or your Rivaro instance URL) instead of the provider directly. Rivaro scans the request, enforces your policies, and forwards it to the real provider. The response comes back through Rivaro unchanged (unless redaction is triggered).

Your Agent → Rivaro Proxy (localhost:8080) → Detection Engine → Policy Engine → LLM Provider

The two things you need:

  1. Base URL: http://localhost:8080/v1 (or https://your-org.rivaro.ai/v1 for cloud)
  2. Detection Key: sent via the X-Detection-Key header

OpenAI SDK (Python)​

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-your-openai-key",
    default_headers={"X-Detection-Key": "YOUR_DETECTION_KEY"}
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Streaming, function calling, tool use, and all other OpenAI features work without changes.

OpenAI SDK (Node.js / TypeScript)​

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8080/v1',
  apiKey: 'sk-your-openai-key',
  defaultHeaders: { 'X-Detection-Key': 'YOUR_DETECTION_KEY' }
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});

LangChain (Python)​

ChatOpenAI​

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o",
    openai_api_key="sk-your-openai-key",
    openai_api_base="http://localhost:8080/v1",
    default_headers={"X-Detection-Key": "YOUR_DETECTION_KEY"}
)

response = llm.invoke("Summarize this document.")

With agents and tools​

from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain.tools import tool

@tool
def search(query: str) -> str:
    """Search the web."""
    return f"Results for: {query}"

llm = ChatOpenAI(
    model="gpt-4o",
    openai_api_key="sk-your-openai-key",
    openai_api_base="http://localhost:8080/v1",
    default_headers={"X-Detection-Key": "YOUR_DETECTION_KEY"}
)

agent = create_openai_tools_agent(llm, [search], prompt)
executor = AgentExecutor(agent=agent, tools=[search])
result = executor.invoke({"input": "Find the latest AI news"})

All tool calls are visible in the Rivaro dashboard. If a tool call triggers a detection (e.g., accessing a sensitive file), the configured policy action is enforced.

LangChain.js​

import { ChatOpenAI } from '@langchain/openai';

const llm = new ChatOpenAI({
  modelName: 'gpt-4o',
  openAIApiKey: 'sk-your-openai-key',
  configuration: {
    baseURL: 'http://localhost:8080/v1',
    defaultHeaders: { 'X-Detection-Key': 'YOUR_DETECTION_KEY' }
  }
});

const response = await llm.invoke('Hello!');

CrewAI​

CrewAI uses the OpenAI SDK under the hood. Configure the environment variables and pass headers via the LLM config:

import os
os.environ["OPENAI_API_KEY"] = "sk-your-openai-key"
os.environ["OPENAI_API_BASE"] = "http://localhost:8080/v1"

from crewai import Agent, Task, Crew

researcher = Agent(
    role="Senior Research Analyst",
    goal="Find and analyze market trends",
    backstory="Expert at analyzing market data",
    llm_config={
        "headers": {"X-Detection-Key": "YOUR_DETECTION_KEY"}
    }
)

task = Task(
    description="Analyze the latest AI market trends",
    expected_output="A detailed market analysis report",
    agent=researcher
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()

Vercel AI SDK​

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const model = openai('gpt-4o', {
  baseURL: 'http://localhost:8080/v1',
  headers: { 'X-Detection-Key': 'YOUR_DETECTION_KEY' }
});

const { text } = await generateText({
  model,
  prompt: 'Explain quantum computing in simple terms.',
});

With streaming​

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

const model = openai('gpt-4o', {
  baseURL: 'http://localhost:8080/v1',
  headers: { 'X-Detection-Key': 'YOUR_DETECTION_KEY' }
});

const result = streamText({
  model,
  prompt: 'Write a short story.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

AutoGen​

AutoGen agents use the OpenAI SDK configuration. Set the base URL in the LLM config list:

import autogen

config_list = [
    {
        "model": "gpt-4o",
        "api_key": "sk-your-openai-key",
        "base_url": "http://localhost:8080/v1",
        "default_headers": {"X-Detection-Key": "YOUR_DETECTION_KEY"}
    }
]

assistant = autogen.AssistantAgent(
    name="assistant",
    llm_config={"config_list": config_list}
)

user_proxy = autogen.UserProxyAgent(
    name="user_proxy",
    code_execution_config={"work_dir": "coding"}
)

user_proxy.initiate_chat(assistant, message="Write a Python script to analyze data.")

Any OpenAI-compatible client​

If your framework or language isn't listed here, the pattern is the same:

  1. Set the base URL to http://localhost:8080/v1 (or /v1 for OpenAI-compatible, bare host for Anthropic)
  2. Add X-Detection-Key: YOUR_DETECTION_KEY as a default header
  3. Keep your provider API key as-is

Rivaro supports the full OpenAI API surface including:

  • Chat completions (streaming and non-streaming)
  • Embeddings
  • Audio (transcription, speech)
  • Images
  • Function/tool calling
  • Structured outputs

Using Anthropic through Rivaro​

For Anthropic's native SDK (not via OpenAI compatibility):

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-ant-your-key",
    base_url="http://localhost:8080",
    default_headers={"X-Detection-Key": "YOUR_DETECTION_KEY"}
)

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

See Anthropic Provider Guide for full details.

MCP tool governance​

If your agent uses MCP (Model Context Protocol) for tool access, Rivaro can govern MCP tool invocations at the gateway level. See MCP Governance for setup instructions.

Next steps​