### Start LiteLLM Proxy Server

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/litellm.mdx

This command sequence demonstrates how to install LiteLLM with proxy support and start the proxy server using a configuration file. The proxy will then be accessible on `http://0.0.0.0:4000`.

```bash
# Install LiteLLM
pip install 'litellm[proxy]'

# Start the proxy with your config
litellm --config config.yaml

# The proxy will run on http://0.0.0.0:4000
```

--------------------------------

### Node.js Deployment for Superagent AI

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/deployment.mdx

Sets up the Superagent AI firewall for Node.js environments. This involves cloning the repository, navigating to the Node.js specific directory, installing dependencies with `npm install`, and starting the application with `npm start`.

```bash
git clone https://github.com/superagent-ai/superagent.git
cd superagent/node
npm install
npm start
```

--------------------------------

### Complete opencode.json Example with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/coding-agents/opencode.mdx

This is a comprehensive example of an `opencode.json` file. It includes the Superagent model configuration along with other settings like theme, autoupdate, and permission handling, demonstrating a full setup.

```json
{
  "model": {
    "provider": "superagent",
    "name": "gpt-4",
    "baseUrl": "YOUR_SUPERAGENT_PROXY_URL"
  },
  "theme": "dark",
  "autoupdate": true,
  "permission": "ask"
}
```

--------------------------------

### Superagent CLI Development Setup

Source: https://github.com/superagent-ai/superagent/blob/main/cli/README.md

Instructions for setting up the Superagent CLI for local development, including installing dependencies, building the project, and testing commands locally using Node.js.

```bash
# Install dependencies
npm install

# Build
npm run build

# Test locally
node dist/index.js guard "test prompt"
```

--------------------------------

### Local Development Setup with uv

Source: https://github.com/superagent-ai/superagent/blob/main/sdk/python/README.md

Sets up the local development environment for the Superagent Python SDK using uv. This includes installing the package in editable mode and its test dependencies.

```bash
cd sdk/python
uv sync --extra tests
```

--------------------------------

### Install Superagent Python SDK

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/python-sdk.mdx

This command installs the Superagent Python SDK using 'uv'. It's recommended to use 'uv add' to pin the dependency and 'uv run' for executing examples without a dedicated virtual environment.

```bash
uv add superagent-ai
```

--------------------------------

### Docker Deployment for Superagent AI

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/deployment.mdx

Deploys the Superagent AI firewall using Docker Compose. This is the recommended and fastest method for getting started. It clones the repository, navigates to the directory, and starts the services with `docker-compose up -d`.

```bash
git clone https://github.com/superagent-ai/superagent.git
cd superagent
docker-compose up -d
```

--------------------------------

### Run Superagent Node.js Proxy

Source: https://github.com/superagent-ai/superagent/blob/main/README.md

Sets up and starts the Superagent Node.js proxy. This involves navigating to the proxy directory, installing dependencies, and starting the service to route AI API traffic securely.

```bash
cd proxy/node/
npm install
npm start
```

--------------------------------

### Install and Test Superagent CLI for Prompt Validation

Source: https://context7.com/superagent-ai/superagent/llms.txt

This bash script demonstrates how to install the Superagent CLI, verify its installation, and manually test the 'superagent guard' command with different prompt inputs. It shows how malicious prompts are blocked and safe prompts proceed silently.

```bash
# Install CLI globally
npm install -g @superagent-ai/cli

# Verify installation
superagent --help

# Test the hook manually
echo '{"prompt": "rm -rf /"}' | superagent guard
# Output: {"decision": "block", "reason": "🛡️ Superagent Guard blocked..."}

# Safe prompts proceed normally
echo '{"prompt": "Write hello world"}' | superagent guard
# No output (passes silently)

# Now all Claude Code prompts are automatically validated
# Malicious prompts are blocked before execution
# Safe prompts proceed without interruption
```

--------------------------------

### Example vibekit.yaml Configuration for Superagent AI

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/deployment.mdx

An example configuration file (`vibekit.yaml`) for Superagent AI, defining AI models and their respective providers and endpoints. This file is crucial for specifying which AI models Superagent should use.

```yaml
models:
  - name: "openai-gpt-4"
    provider: "openai"
    endpoint: "https://api.openai.com/v1"
  - name: "anthropic-claude"
    provider: "anthropic"
    endpoint: "https://api.anthropic.com/v1"
```

--------------------------------

### Install Dependencies for Mastra and Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/examples/mastra.mdx

Installs the necessary packages for Mastra core, Superagent AI, Zod for validation, and the OpenAI SDK. This command is executed in the terminal.

```bash
npm install @mastra/core superagent-ai zod @ai-sdk/openai
```

--------------------------------

### Install Dependencies for Superagent AI

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/examples/e2b.mdx

Installs necessary npm packages for using OpenAI, E2B Code Interpreter, and Superagent AI in a TypeScript project. This is a prerequisite for running the provided code examples.

```bash
npm install openai e2b-code-interpreter superagent-ai
```

--------------------------------

### Superagent Configuration Example

Source: https://github.com/superagent-ai/superagent/blob/main/README.md

Example configuration file for Superagent, specifying AI models and providers like OpenAI and Anthropic. It also shows how to configure an optional telemetry webhook for sending data.

```yaml
models:
  - model_name: "gpt-5"
    provider: "openai"
    api_base: "https://api.openai.com"

  - model_name: "claude-sonnet-4-5"
    provider: "anthropic"
    api_base: "https://api.anthropic.com/v1"

# Optional: Send telemetry to external webhook
telemetry_webhook:
  url: "https://your-webhook.com/api/telemetry"
  headers:
    x-api-key: "your-api-key"
```

--------------------------------

### Install Dependencies for Secure Search Agent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/examples/firecrawl.mdx

Installs necessary packages for creating a secure web search agent, including AI SDKs, Superagent, Firecrawl, and environment variable management.

```bash
npm install ai @ai-sdk/openai superagent-ai zod @mendable/firecrawl-js dotenv
```

--------------------------------

### Install Superagent CLI

Source: https://github.com/superagent-ai/superagent/blob/main/README.md

Installs the Superagent command-line interface globally using npm. The CLI is used for managing and interacting with Superagent functionalities.

```bash
npm install -g @superagent-ai/cli
```

--------------------------------

### Install Dependencies for Superagent and E2B

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/examples/e2b.mdx

This command installs the necessary Python packages: openai for interacting with OpenAI's models, e2b-code-interpreter for running code in isolated environments, and superagent-ai for code guarding.

```bash
pip install openai e2b-code-interpreter superagent-ai
```

--------------------------------

### Build and Run Superagent Rust Proxy

Source: https://github.com/superagent-ai/superagent/blob/main/README.md

Compiles and runs the high-performance Superagent Rust proxy. This process involves building the release version and then starting the AI firewall service.

```bash
cd proxy/rust/
cargo build --release
./target/release/ai-firewall start
```

--------------------------------

### Install Superagent AI SDK using npm, pnpm, or yarn

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/agent-frameworks/vercel-ai-sdk.mdx

This snippet shows how to add the Superagent AI SDK to your project using common package managers. Ensure you have Node.js v20.0 or higher installed.

```bash
npm install superagent-ai
# or
pnpm add superagent-ai
# or
yarn add superagent-ai
```

--------------------------------

### Deploy LiteLLM Proxy using Docker

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/litellm.mdx

This Dockerfile specifies how to build a Docker image for the LiteLLM proxy. It uses a base image, copies a configuration file, exposes port 4000, and sets the command to start the proxy with the provided configuration.

```dockerfile
FROM ghcr.io/berriai/litellm:main-latest

# Copy your config
COPY config.yaml /app/config.yaml

# Expose port
EXPOSE 4000

# Start with config
CMD ["--config", "/app/config.yaml"]
```

--------------------------------

### Installing Superagent CLI Globally Without Sudo (Bash)

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/cli.mdx

This bash script configures npm to install global packages to a user-specific directory and updates the PATH to include them, avoiding permission issues when installing with 'npm install -g'.

```bash
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g @superagent-ai/cli
```

--------------------------------

### Install Superagent CLI

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/examples/claude-code-userprompt.mdx

Installs the Superagent Command Line Interface globally using npm. This tool is essential for interacting with the Superagent API to guard prompts.

```bash
npm i -g @superagent-ai/cli
```

--------------------------------

### Install Superagent Python SDK

Source: https://github.com/superagent-ai/superagent/blob/main/README.md

Installs the Superagent Python SDK using pip. This SDK allows for direct validation of actions within your Python application without needing to run the proxy separately.

```bash
pip install superagent-ai
```

--------------------------------

### Install Superagent TypeScript SDK

Source: https://github.com/superagent-ai/superagent/blob/main/README.md

Installs the Superagent TypeScript SDK using npm. This SDK enables direct validation of actions within your TypeScript application, complementing the proxy service.

```bash
npm install superagent-ai
```

--------------------------------

### Install Mastra and Superagent Dependencies

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/agent-frameworks/mastra.mdx

Installs the necessary packages for Mastra core, Superagent AI, Zod for validation, and OpenAI SDK. Supports npm, pnpm, and yarn package managers.

```bash
npm install @mastra/core superagent-ai zod @ai-sdk/openai
# or
pnpm add @mastra/core superagent-ai zod @ai-sdk/openai
# or
yarn add @mastra/core superagent-ai zod @ai-sdk/openai
```

--------------------------------

### Run Test Suite with uv

Source: https://github.com/superagent-ai/superagent/blob/main/sdk/python/README.md

Executes the test suite for the Superagent Python SDK using uv. Ensures the library is functioning correctly after setup.

```bash
uv run pytest tests
```

--------------------------------

### Superagent Python SDK Usage Example

Source: https://github.com/superagent-ai/superagent/blob/main/sdk/python/README.md

Demonstrates how to use the Superagent Python SDK to initialize a client and utilize the Guard and Redact functionalities. It shows how to analyze commands for security threats and redact sensitive information from text.

```python
import asyncio
from superagent_ai import create_client

async def main() -> None:
    client = create_client(
        api_base_url="https://app.superagent.sh/api",  # Optional, this is the default
        api_key="sk-ாலத்தில்",
    )

    # Guard: Analyze commands for security threats
    guard_result = await client.guard(
        "Write a hello world script",
        on_block=lambda reason: print("Guard blocked:", reason),
        on_pass=lambda: print("Guard approved!"),
    )

    if guard_result.rejected:
        print("Rejected:", guard_result.reasoning)
    else:
        print("Approved:", guard_result.decision)

    # Redact: Remove sensitive data from text
    redact_result = await client.redact(
        "My email is john@example.com and SSN is 123-45-6789"
    )

    print(redact_result.redacted)
    # Output: "My email is <REDACTED_EMAIL> and SSN is <REDACTED_SSN>"

    await client.aclose()

asyncio.run(main())
```

--------------------------------

### Install Superagent AI and LangGraph Dependencies

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/agent-frameworks/langgraph.mdx

Installs the necessary Python packages for Superagent AI, LangGraph, and Langchain OpenAI integration using 'uv'. This command ensures all required libraries are available for building guarded LLM workflows.

```bash
uv add superagent-ai langgraph langchain-openai langchain-core
```

--------------------------------

### Rust Deployment for Superagent AI

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/deployment.mdx

Provides a high-performance deployment option for Superagent AI using Rust. It clones the repository, navigates to the Rust directory, builds the release version using `cargo build --release`, and then starts the AI firewall.

```bash
git clone https://github.com/superagent-ai/superagent.git
cd superagent/rust
cargo build --release
./target/release/ai-firewall start
```

--------------------------------

### TypeScript OpenAI SDK Setup for Gemini with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/gemini-sdk.mdx

Provides an example of using the OpenAI TypeScript SDK to connect to Gemini models through Superagent. Configuring the `baseURL` in the `OpenAI` client constructor with your Superagent proxy URL enables access to Gemini's OpenAI-compatible endpoints with added security.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
  apiKey: 'your-gemini-api-key',
});

// Many Gemini endpoints are OpenAI compatible
```

--------------------------------

### TypeScript/JavaScript SDK Setup with Superagent Proxy

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/groq-sdk.mdx

Set up the Groq TypeScript/JavaScript SDK to utilize a Superagent proxy by specifying the `baseURL`. This integrates AI firewall protection seamlessly into your existing Groq applications. Dependencies: `groq-sdk`.

```typescript
import Groq from 'groq-sdk';

const groq = new Groq({
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
  apiKey: 'your-groq-api-key',
});

// Use the client as usual - no other changes needed
const chatCompletion = await groq.chat.completions.create({
  messages: [
    {
      role: 'user',
      content: 'Explain the importance of fast inference for AI applications.',
    }
  ],
  model: 'llama-3.3-70b-versatile',
});
```

--------------------------------

### Node.js Proxy - Running the Server

Source: https://context7.com/superagent-ai/superagent/llms.txt

Instructions to start the Node.js Superagent proxy server programmatically or via command line. It supports automatic request/response redaction and threat detection. Configuration can be managed via a YAML file and environment variables like REDIS_URL and MULTITENANT.

```javascript
// Start proxy programmatically
import ProxyServer from './src/server.js';

const server = new ProxyServer(
  8080,                                    // Port
  'superagent.yaml',                       // Config path
  'https://api.superagent.sh/api'          // Redaction API URL
);

await server.start();
console.log('Proxy listening on port 8080');

// Use with environment variables
process.env.MULTITENANT = 'true';
process.env.REDIS_URL = 'redis://localhost:6379';
process.env.MULTITENANT_CONFIG_API_URL = 'https://api.example.com/config/';
process.env.CONFIG_CACHE_TTL = '3600';
```

```bash
# Start from command line
cd proxy/node/
npm install
npm start

# With environment variables
export MULTITENANT=true
export REDIS_URL=redis://localhost:6379
export NINJA_LM_API_URL=https://api.superagent.sh
node src/index.js

# Docker deployment
docker-compose up -d

# Client usage - point your OpenAI client to the proxy
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_KEY" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello world"}]
  }'
```

--------------------------------

### Install Superagent and LangGraph Dependencies (TypeScript)

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/agent-frameworks/langgraph.mdx

Installs necessary npm packages for integrating Superagent with LangGraph and OpenAI. Ensure Node.js v20.0 or higher is installed.

```bash
npm install superagent-ai @langchain/langgraph @langchain/openai @langchain/core zod
```

--------------------------------

### TypeScript/JavaScript SDK Setup with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/xai-sdk.mdx

Set up the xAI TypeScript/JavaScript SDK to route requests through Superagent. Initialize the SDK with your API key and the Superagent proxy URL. This ensures all subsequent calls benefit from Superagent's AI firewall.

```typescript
import { createXai } from '@ai-sdk/xai';

const xai = createXai({
  apiKey: 'your-xai-api-key',
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
});

// Use the client as usual - no other changes needed
```

--------------------------------

### Python SDK Setup with Superagent Proxy

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/groq-sdk.mdx

Configure the Groq Python SDK to use a Superagent proxy by setting the `base_url`. This enables AI firewall protection for your Groq applications with no other code changes required. Dependencies: `groq` library.

```python
from groq import Groq

client = Groq(
    base_url="YOUR_SUPERAGENT_PROXY_URL",  # Replace with your Superagent proxy
    api_key="your-groq-api-key"
)

# Use the client as usual - no other changes needed
chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "Explain the importance of fast inference for AI applications.",
        }
    ],
    model="llama-3.3-70b-versatile",
)
```

--------------------------------

### Use LiteLLM Proxy with TypeScript OpenAI Client

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/litellm.mdx

This TypeScript example illustrates connecting to your Superagent-protected LiteLLM proxy. It configures the OpenAI client with the proxy's URL and makes a chat completion request, similar to the Python example, using a model defined in your LiteLLM configuration.

```typescript
import OpenAI from 'openai';

// Connect to your protected LiteLLM proxy
const client = new OpenAI({
  apiKey: 'anything', // LiteLLM proxy authentication
  baseURL: 'http://localhost:4000', // Your LiteLLM proxy URL
});

// Use any configured model
const response = await client.chat.completions.create({
  model: 'claude-3-opus', // Model name from your config
  messages: [{ role: 'user', content: 'Hello world' }],
});
```

--------------------------------

### Adding npm Global Bin to PATH (Bash)

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/cli.mdx

This bash snippet shows how to find the npm global bin directory and add it to your system's PATH. This is necessary to run globally installed npm packages like 'superagent'.

```bash
npm config get prefix
# Add the bin directory to your PATH
export PATH="$(npm config get prefix)/bin:$PATH"
```

--------------------------------

### Python SDK Setup with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/xai-sdk.mdx

Configure the xAI Python SDK to use Superagent's proxy URL. This requires initializing the client with your API key and the Superagent proxy URL, enabling AI firewall protection for your requests without altering existing SDK usage.

```python
from xai_sdk import Client

client = Client(
    api_key="your-xai-api-key",
    base_url="YOUR_SUPERAGENT_PROXY_URL"  # Replace with your Superagent proxy
)

# Use the client as usual - no other changes needed
```

--------------------------------

### TypeScript/JavaScript SDK Setup with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/anthropic-sdk.mdx

This code snippet shows how to set up the Anthropic TypeScript/JavaScript SDK with Superagent. Replace `baseURL` with your Superagent proxy URL and include your Anthropic API key. This setup allows your existing Anthropic SDK code to function unchanged while benefiting from Superagent's AI firewall.

```typescript
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
  apiKey: 'your-anthropic-api-key',
});

// Use the client as usual - no other changes needed
```

--------------------------------

### cURL Request Example for OpenRouter

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/openrouter-sdk.mdx

Demonstrates how to make a cURL request to the Superagent proxy URL for OpenRouter integration. This includes setting the necessary headers and payload for chat completions, benefiting from Superagent's AI firewall.

```bash
curl "YOUR_SUPERAGENT_PROXY_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-openrouter-api-key" \
  -d '{
    "model": "anthropic/claude-3-sonnet",
    "messages": [
      {
        "role": "user",
        "content": "Hello, world!"
      }
    ]
  }'
```

--------------------------------

### Run Superagent via Docker Compose

Source: https://github.com/superagent-ai/superagent/blob/main/README.md

Starts the Superagent proxy service using Docker Compose. This command spins up the necessary containers in detached mode for background operation.

```bash
docker-compose up -d
```

--------------------------------

### TypeScript with OpenAI SDK and Superagent Proxy

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/vercel-ai-gateway.mdx

Provides an example of configuring the OpenAI TypeScript SDK to route requests through a Superagent proxy for Vercel AI Gateway models. This ensures secure access to AI models. Requires an API key and the Superagent proxy URL.

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-vercel-ai-gateway-api-key',
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
});

// Use any model from Vercel AI Gateway
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Hello world' }],
});
```

--------------------------------

### Python SDK Setup for OpenRouter

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/openrouter-sdk.mdx

Configure the OpenAI client in Python to use the Superagent proxy URL for integrating with OpenRouter. This allows AI firewall protection for existing OpenRouter applications without code changes beyond the base URL.

```python
from openai import OpenAI

client = OpenAI(
    base_url="YOUR_SUPERAGENT_PROXY_URL",  # Replace with your Superagent proxy
    api_key="your-openrouter-api-key"
)

# Use the client as usual - no other changes needed
```

--------------------------------

### Example Hook Input JSON

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/examples/claude-code-userprompt.mdx

Illustrates the JSON structure passed to the 'superagent guard' command when the UserPromptSubmit hook is triggered by Claude Code. This includes the user's prompt, session ID, and current working directory.

```json
{
  "prompt": "User's prompt text here",
  "session_id": "abc123",
  "cwd": "/current/working/dir"
}
```

--------------------------------

### Quick Start: Superagent Python Client Usage

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/python-sdk.mdx

Demonstrates how to create a Superagent client and use its Guard and Redact functionalities. The Guard endpoint analyzes commands for security threats, while the Redact endpoint removes sensitive data from text. The client is closed after use.

```python
import asyncio
from superagent_ai import create_client

async def main() -> None:
    client = create_client(
        api_base_url="https://app.superagent.sh/api",  # Optional, this is the default
        api_key="sk-...",
    )

    # Guard: Analyze commands for security threats
    guard_result = await client.guard(
        "Write a hello world script",
        on_block=lambda reason: print("Guard blocked:", reason),
        on_pass=lambda: print("Guard approved!"),
    )

    if guard_result.rejected:
        print("Rejected:", guard_result.reasoning)
    else:
        print("Approved:", guard_result.decision)

    # Redact: Remove sensitive data from text
    redact_result = await client.redact(
        "My email is john@example.com and SSN is 123-45-6789"
    )

    print(redact_result.redacted)
    # Output: "My email is <REDACTED_EMAIL> and SSN is <REDACTED_SSN>"

    await client.aclose()

asyncio.run(main())
```

--------------------------------

### Python SDK Setup for Gemini with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/gemini-sdk.mdx

Demonstrates how to configure the Google Gemini Python SDK to use Superagent as a proxy. This involves setting the `base_url` in the `Client` initialization to your Superagent proxy URL, enabling AI firewall protection without altering other SDK usage.

```python
from google import genai

client = genai.Client(
    api_key="your-gemini-api-key",
    http_options={'base_url': 'YOUR_SUPERAGENT_PROXY_URL'}  # Replace with your Superagent proxy
)

# Use the client as usual - no other changes needed
```

--------------------------------

### TypeScript/JavaScript SDK Setup for Gemini with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/gemini-sdk.mdx

Illustrates configuring the Google Gemini TypeScript/JavaScript SDK to route through Superagent. The `baseUrl` parameter in the `GoogleGenAI` constructor should be updated to your Superagent proxy URL, allowing for AI firewall protection with no other code modifications.

```typescript
import { GoogleGenAI } from '@google/genai';

const genai = new GoogleGenAI({
  apiKey: 'your-gemini-api-key',
  baseUrl: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
});

// Use the client as usual - no other changes needed
```

--------------------------------

### Python SDK Setup for Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/openai-sdk.mdx

This snippet demonstrates how to configure the OpenAI Python SDK to use Superagent's proxy URL. Update the `base_url` parameter with your Superagent proxy address. No other code modifications are necessary for existing OpenAI SDK usage.

```python
from openai import OpenAI

client = OpenAI(
    base_url="YOUR_SUPERAGENT_PROXY_URL",  # Replace with your Superagent proxy
    api_key="your-openai-api-key"
)

# Use the client as usual - no other changes needed
```

--------------------------------

### TypeScript/JavaScript SDK Setup for Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/openai-sdk.mdx

This snippet shows how to configure the OpenAI TypeScript/JavaScript SDK to utilize Superagent's proxy. Set the `baseURL` option to your Superagent proxy URL. Existing OpenAI SDK methods and parameters remain fully compatible.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
  apiKey: 'your-openai-api-key',
});

// Use the client as usual - no other changes needed
```

--------------------------------

### Guard Tool Execution with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/agent-frameworks/vercel-ai-sdk.mdx

This TypeScript example shows how to guard a tool execution, specifically a shell command, using the Superagent guard. The `guard` client is used within the tool's `execute` function to validate the input command before running it. If the command is blocked, it returns null for the result; otherwise, it executes the shell command and returns the result.

```typescript
import { streamText, tool } from "ai";
import { z } from "zod";
import { createGuard } from "superagent-ai";

const guard = createGuard({ apiKey: process.env.SUPERAGENT_API_KEY })

const runCommand = tool({
  description: "Execute a shell command",
  inputSchema: z.object({
    command: z.string().describe("The shell command to execute")
  }),
  execute: async ({ command }) => {
    const { decision, reasoning, rejected } = await guard(command, {
      onBlock: () => console.warn("Tool call blocked:", reasoning),
    });

    if (rejected) {
      return {
        result: null,
        safetyAnalysis: {
          decision,
          reasoning
        }
      };
    }

    const result = await runShellCommand(command);

    return {
      result,
      safetyAnalysis: {
        decision,
        reasoning
      }
    }
  },
});

const result = await streamText({
  model: openai("gpt-5"),
  prompt: "Inspect the repository and summarize the README.",
  tools: { runCommand },
});
```

--------------------------------

### Python OpenAI SDK Setup for Gemini with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/gemini-sdk.mdx

Shows how to leverage the OpenAI Python SDK to interact with Gemini models via Superagent. By setting the `base_url` in the `OpenAI` client to your Superagent proxy, you can utilize Gemini endpoints with OpenAI-compatible features and Superagent's protection.

```python
from openai import OpenAI

client = OpenAI(
    base_url="YOUR_SUPERAGENT_PROXY_URL",  # Replace with your Superagent proxy
    api_key="your-gemini-api-key"
)

# Many Gemini endpoints are OpenAI compatible
```

--------------------------------

### Update OpenAI SDK with Superagent Proxy (Python & TypeScript)

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/proxy.mdx

This snippet demonstrates how to configure the OpenAI SDK in both Python and TypeScript to use a Superagent proxy link. Replace 'YOUR_PROXY_LINK_HERE' with your actual Superagent proxy URL and 'your-openai-api-key' with your OpenAI API key. This allows your application's API requests to be routed through Superagent while maintaining full compatibility with the OpenAI API.

```python
from openai import OpenAI

client = OpenAI(
    base_url="YOUR_PROXY_LINK_HERE",  # Replace with your proxy link
    api_key="your-openai-api-key"
)

# Use the client as usual
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello, world!"}]
)
```

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'YOUR_PROXY_LINK_HERE', // Replace with your proxy link
  apiKey: 'your-openai-api-key',
});

// Use the client as usual
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello, world!' }],
});
```

--------------------------------

### Python SDK Setup with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/anthropic-sdk.mdx

This code snippet demonstrates how to configure the Anthropic Python SDK to use Superagent's proxy. Update the `base_url` parameter to your Superagent proxy URL and provide your Anthropic API key. No other code changes are necessary to leverage Superagent's AI firewall protection.

```python
import anthropic

client = anthropic.Anthropic(
    base_url="YOUR_SUPERAGENT_PROXY_URL",  # Replace with your Superagent proxy
    api_key="your-anthropic-api-key"
)

# Use the client as usual - no other changes needed
```

--------------------------------

### Configure LiteLLM Python SDK with Custom Endpoint

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/litellm.mdx

This snippet shows how to use the LiteLLM Python SDK to send completion requests through a Superagent proxy. Ensure you have LiteLLM installed and your API keys set as environment variables. The `api_base` parameter must be set to your Superagent proxy URL.

```python
from litellm import completion
import os

# Set your API keys
os.environ["OPENAI_API_API_KEY"] = "your-openai-api-key"

# Route through Superagent proxy
response = completion(
    model="openai/gpt-4o",
    messages=[{"content": "Hello world", "role": "user"}],
    api_base="YOUR_SUPERAGENT_PROXY_URL"  # Replace with your Superagent proxy
)

print(response.choices[0].message.content)
```

--------------------------------

### Client Creation

Source: https://github.com/superagent-ai/superagent/blob/main/sdk/typescript/README.md

Demonstrates how to create a Superagent client instance with essential configuration options.

```APIDOC
## Client Creation

### Description
Creates a new Superagent client instance.

### Method
`createClient(options)`

### Parameters
#### Options
- **apiKey** (string) - Required - API key provisioned in Superagent.
- **apiBaseUrl** (string) - Optional - Base URL for the API (defaults to `https://app.superagent.sh/api`).
- **fetch** (Function) - Optional - Custom fetch implementation (defaults to global `fetch`).
- **timeoutMs** (number) - Optional - Request timeout in milliseconds.

### Request Example
```typescript
import { createClient } from "superagent-ai";

const client = createClient({
  apiBaseUrl: process.env.SUPERAGENT_API_BASE_URL, 
  apiKey: process.env.SUPERAGENT_API_KEY!,
});
```
```

--------------------------------

### Python SDK: Create Superagent Client

Source: https://context7.com/superagent-ai/superagent/llms.txt

Initializes the asynchronous Superagent client, supporting optional context manager usage. It requires an API key and can optionally take a base URL and timeout. The client should be closed after use or managed with a context manager.

```python
import asyncio
from superagent_ai import create_client, GuardError

async def main():
    # Basic client creation
    client = create_client(
        api_key="sk-your-api-key",
        api_base_url="https://app.superagent.sh/api",  # Optional
        timeout=10.0  # Optional timeout in seconds
    )

    try:
        result = await client.guard("Write a hello world script")
        print(f"Approved: {not result.rejected}")
    finally:
        await client.aclose()  # Always close the client

async def context_manager_usage():
    # Using context manager (recommended)
    async with create_client(api_key="sk-your-api-key") as client:
        result = await client.guard("rm -rf /")
        if result.rejected:
            print(f"Blocked: {result.reasoning}")
            print(f"Violations: {result.decision.violation_types}")
        # Client automatically closed after context exits

asyncio.run(main())
```

--------------------------------

### Superagent Client Initialization

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/typescript-sdk.mdx

Demonstrates how to create a Superagent client instance with API key and optional configurations.

```APIDOC
## `createClient(options)`

### Description
Creates a new Superagent client.

### Method
`createClient`

### Parameters
#### Request Body
- **apiKey** (string) - Required - API key provisioned in Superagent
- **apiBaseUrl** (string) - Optional - Base URL for the API (defaults to `https://app.superagent.sh/api`)
- **fetch** (Function) - Optional - Custom fetch implementation (defaults to global `fetch`)
- **timeoutMs** (number) - Optional - Request timeout in milliseconds

### Request Example
```typescript
import { createClient } from "superagent-ai";

const client = createClient({
  apiBaseUrl: process.env.SUPERAGENT_API_BASE_URL, // Optional, defaults to https://app.superagent.sh/api
  apiKey: process.env.SUPERAGENT_API_KEY!,
});
```
```

--------------------------------

### Initialize Superagent Client (TypeScript)

Source: https://github.com/superagent-ai/superagent/blob/main/sdk/typescript/README.md

Demonstrates how to create a Superagent client instance in TypeScript, configuring API base URL and API key. It handles optional base URL and requires an API key.

```typescript
import { createClient } from "superagent-ai";

const client = createClient({
  apiBaseUrl: process.env.SUPERAGENT_API_BASE_URL, // Optional, defaults to https://app.superagent.sh/api
  apiKey: process.env.SUPERAGENT_API_KEY!,
});
```

--------------------------------

### Custom Configuration Path for Superagent AI

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/deployment.mdx

Demonstrates how to specify a custom configuration file path for Superagent AI during startup. This allows users to use a `vibekit.yaml` file located in a non-default path.

```bash
# Node.js
npm start -- --config /path/to/your/vibekit.yaml

# Rust  
./target/release/ai-firewall start --config /path/to/your/vibekit.yaml
```

--------------------------------

### Validating JSON Input for Superagent Guard (Bash)

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/cli.mdx

This example shows how to pipe valid JSON with a 'prompt' field to the superagent guard command. It's used for validating input when running in stdin mode.

```bash
echo '{"prompt": "your text"}' | superagent guard
```

--------------------------------

### Use LiteLLM Proxy with Python OpenAI SDK

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/litellm.mdx

This Python code snippet shows how to connect to a running LiteLLM proxy, which is protected by Superagent. It initializes the OpenAI client pointing to the local proxy URL and demonstrates making a chat completion request using a model configured in your `config.yaml`.

```python
import openai

# Connect to your LiteLLM proxy (now protected by Superagent)
client = openai.OpenAI(
    api_key="anything",  # LiteLLM proxy doesn't require authentication by default
    base_url="http://localhost:4000"  # Your LiteLLM proxy URL
)

# Use any configured model
response = client.chat.completions.create(
    model="gpt-4o",  # Model name from your config
    messages=[{"role": "user", "content": "Hello world"}]
)
```

--------------------------------

### Configure LiteLLM Proxy with Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/litellm.mdx

This YAML configuration file defines models for LiteLLM to use, pointing them to your Superagent proxy URL. It includes settings for OpenAI, Anthropic, and Grok models, specifying their respective LiteLLM parameters and API keys. Replace placeholder URLs and keys with your actual values.

```yaml
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_base: YOUR_SUPERAGENT_PROXY_URL  # Replace with your Superagent proxy
      api_key: "os.environ/OPENAI_API_KEY"
  
  - model_name: claude-3-opus
    litellm_params:
      model: anthropic/claude-3-opus-20240229
      api_base: YOUR_SUPERAGENT_PROXY_URL  # Replace with your Superagent proxy
      api_key: "os.environ/ANTHROPIC_API_KEY"

  - model_name: grok-3
    litellm_params:
      model: xai/grok-3
      api_base: YOUR_SUPERAGENT_PROXY_URL  # Replace with your Superagent proxy
      api_key: "os.environ/XAI_API_KEY"
```

--------------------------------

### TypeScript/JavaScript SDK Setup for OpenRouter

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/sdks/openrouter-sdk.mdx

Configure the OpenAI client in TypeScript/JavaScript to use the Superagent proxy URL for integrating with OpenRouter. This adds AI firewall protection to existing OpenRouter applications with a simple base URL update.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
  apiKey: 'your-openrouter-api-key',
});

// Use the client as usual - no other changes needed
```

--------------------------------

### Initialize Superagent Client and Use Guard/Redact

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/typescript-sdk.mdx

Demonstrates how to create a Superagent client instance with API key and base URL, then use the `guard` method to analyze commands for security threats and the `redact` method to remove sensitive data from text. Includes handling for guard callbacks and accessing redacted output.

```typescript
import { createClient } from "superagent-ai";

const client = createClient({
  apiBaseUrl: process.env.SUPERAGENT_API_BASE_URL, // Optional, defaults to https://app.superagent.sh/api
  apiKey: process.env.SUPERAGENT_API_KEY!,
});

// Guard: Analyze commands for security threats
const guardResult = await client.guard("Write a hello world script", {
  onBlock: (reason) => {
    console.warn("Guard blocked command:", reason);
  },
  onPass: () => {
    console.log("Guard approved command!");
  },
});

if (guardResult.rejected) {
  console.log("Blocked:", guardResult.reasoning);
} else {
  console.log("Approved");
}

// Redact: Remove sensitive data from text
const redactResult = await client.redact(
  "My email is john@example.com and SSN is 123-45-6789"
);

console.log(redactResult.redacted);
// Output: "My email is <REDACTED_EMAIL> and SSN is <REDACTED_SSN>"
```

--------------------------------

### Rust Proxy - High Performance Mode

Source: https://context7.com/superagent-ai/superagent/llms.txt

Instructions for building and running the high-performance Rust Superagent proxy server, suitable for production environments requiring low latency. It supports multi-tenant routing, health checks, and configuration updates via API endpoints. Environment variables can be used to configure tenancy, Redis, and logging.

```bash
# Build and run Rust proxy
cd proxy/rust/
cargo build --release
./target/release/ai-firewall start --port 8080 --config superagent.yaml

# Run with environment variables
export MULTITENANT=true
export REDIS_URL=redis://localhost:6379
export MULTITENANT_CONFIG_API_URL=https://api.example.com/config/
export LOG_LEVEL=info
./target/release/ai-firewall start

# Health check endpoint
curl http://localhost:8080/health

# Multi-tenant routing (each tenant has their own config)
curl http://localhost:8080/tenant-abc-123/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Write code"}]
  }'

# Config cache update endpoint
curl -X POST http://localhost:8080/config/tenant-abc-123 \
  -H "Content-Type: application/json" \
  -d '{
    "models": [
      {"model_name": "gpt-5", "provider": "openai", "api_base": "https://api.openai.com"}
    ]
  }'
```

--------------------------------

### Superagent Python Client as Context Manager

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/python-sdk.mdx

Shows how to initialize and use the Superagent client within an asynchronous context manager. This approach ensures the client is properly managed and closed after use, simplifying resource handling.

```python
import asyncio
from superagent_ai import create_client

async def main() -> None:
    async with create_client(api_key="sk-...") as client:
        result = await client.guard("command")
        redacted = await client.redact("text")

asyncio.run(main())
```

--------------------------------

### Initialize Superagent Client (TypeScript)

Source: https://context7.com/superagent-ai/superagent/llms.txt

Initializes the Superagent client using API credentials. Supports default or custom API base URLs and configurable timeouts. The client is then used to interact with Superagent's security features.

```typescript
import { createClient } from "superagent-ai";

// Create client with default API base URL
const client = createClient({
  apiKey: process.env.SUPERAGENT_API_KEY!,
});

// Create client with custom API base URL and timeout
const customClient = createClient({
  apiBaseUrl: "https://custom.superagent.sh/api",
  apiKey: "sk-your-api-key",
  timeoutMs: 5000,
});

// Use client to analyze prompts
try {
  const result = await client.guard("Write a hello world script");
  console.log("Approved:", !result.rejected);
} catch (error) {
  console.error("Guard error:", error.message);
}
```

--------------------------------

### Basic opencode.json Configuration for Superagent

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/coding-agents/opencode.mdx

This JSON snippet demonstrates the basic configuration required in `opencode.json` to use Superagent as the model provider. It specifies the provider as 'superagent', selects a model ('gpt-4'), and requires the user to input their Superagent proxy URL.

```json
{
  "model": {
    "provider": "superagent",
    "name": "gpt-4",
    "baseUrl": "YOUR_SUPERAGENT_PROXY_URL"
  }
}
```

--------------------------------

### Use Gateway Provider with AI SDK

Source: https://github.com/superagent-ai/superagent/blob/main/docs/content/docs/ai-gateways/vercel-ai-gateway.mdx

Demonstrates how to integrate the Superagent gateway provider with the AI SDK to route requests and leverage AI firewall protection. Requires an API key and the Superagent proxy URL.

```typescript
import { gateway } from '@ai-sdk/gateway';
import { generateText } from 'ai';

const gatewayProvider = gateway({
  apiKey: 'your-vercel-ai-gateway-api-key',
  baseURL: 'YOUR_SUPERAGENT_PROXY_URL', // Replace with your Superagent proxy
});

// Use with any Vercel AI Gateway model
const { text } = await generateText({
  model: gatewayProvider('xai/grok-3'),
  prompt: 'Explain quantum computing',
});
```

--------------------------------

### Superagent Python SDK Context Manager Usage

Source: https://github.com/superagent-ai/superagent/blob/main/sdk/python/README.md

Illustrates using the Superagent client as an asynchronous context manager. This ensures the client is properly initialized and closed.

```python
import asyncio
from superagent_ai import create_client

async def main() -> None:
    async with create_client(api_key="sk-ாலத்தில்") as client:
        result = await client.guard("command")
        redacted = await client.redact("text")

asyncio.run(main())
```