mirror of
https://github.com/invariantlabs-ai/invariant-gateway.git
synced 2026-03-11 21:06:20 +00:00
142 lines
4.9 KiB
Markdown
142 lines
4.9 KiB
Markdown
# **Invariant Proxy**
|
|
|
|
Invariant Proxy is a lightweight Docker service that acts as an intermediary between AI Agents and LLM providers (such as OpenAI and Anthropic). It captures and forwards agent interactions to the [Invariant Explorer](https://explorer.invariantlabs.ai/), enabling seamless debugging, visualization, and exploration of traces.
|
|
|
|
|
|
|
|
---
|
|
|
|
## **Why Use Invariant Proxy?**
|
|
- ✅ **Intercept AI interactions** for better debugging and analysis.
|
|
- ✅ **Seamlessly forward API requests** to OpenAI, Anthropic, and other LLM providers (**supports streaming responses too**).
|
|
- ✅ **Works with AI Agent platforms and systems** like OpenHands, SWE-agent, etc.
|
|
- ✅ **Automatically store and organize traces** in the Invariant Explorer.
|
|
|
|
---
|
|
|
|
## **Getting Started**
|
|
|
|
### **Run the Proxy Locally**
|
|
To start the Invariant Proxy, run:
|
|
|
|
```bash
|
|
bash run.sh build && bash run.sh up
|
|
```
|
|
|
|
This will launch the proxy at [http://localhost:8005/api/v1/proxy/](http://localhost:8005/api/v1/proxy/docs/).
|
|
|
|
### **Set Up an Invariant API Key**
|
|
1. Follow the instructions [here](https://explorer.invariantlabs.ai/docs/explorer/Explorer_API/1_client_setup/) to obtain an API key. This allows the proxy to push traces to [Invariant Explorer](https://explorer.invariantlabs.ai).
|
|
|
|
---
|
|
|
|
## **Integration Guides**
|
|
|
|
### **🔹 OpenAI Integration**
|
|
|
|
1. Follow [these steps](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) to obtain an OpenAI API key.
|
|
2. **Modify OpenAI Client Setup**
|
|
|
|
Instead of connecting directly to OpenAI, configure your `OpenAI` client to use the proxy:
|
|
|
|
```python
|
|
from httpx import Client
|
|
from openai import OpenAI
|
|
|
|
client = OpenAI(
|
|
http_client=Client(
|
|
headers={
|
|
"Invariant-Authorization": "Bearer your-invariant-api-key"
|
|
},
|
|
),
|
|
base_url="http://localhost:8005/api/v1/proxy/{add-your-dataset-name-here}/openai",
|
|
)
|
|
```
|
|
|
|
> **Note:** Do not include the curly braces `{}`. If the dataset does not exist in Invariant Explorer, it will be created before adding traces.
|
|
|
|
### **🔹 Anthropic Integration**
|
|
|
|
1. Follow [these steps](https://docs.anthropic.com/en/docs/initial-setup#set-your-api-key) to obtain an Anthropic API key.
|
|
2. **Modify Anthropic Client Setup**
|
|
|
|
```python
|
|
from httpx import Client
|
|
from anthropic import Anthropic
|
|
|
|
client = Anthropic(
|
|
http_client=Client(
|
|
headers={
|
|
"Invariant-Authorization": "Bearer your-invariant-api-key"
|
|
},
|
|
),
|
|
base_url="http://localhost:8005/api/v1/proxy/{add-your-dataset-name-here}/anthropic",
|
|
)
|
|
```
|
|
|
|
> **Note:** Do not include the curly braces `{}`. If the dataset does not exist in Invariant Explorer, it will be created before adding traces.
|
|
---
|
|
|
|
## **OpenHands Integration**
|
|
[OpenHands](https://github.com/All-Hands-AI/OpenHands) (formerly OpenDevin) is a platform for software development agents powered by AI.
|
|
|
|
### **How to Integrate OpenHands with Invariant Proxy**
|
|
|
|
#### **Step 1: Modify the API Base**
|
|
Enable the `Advanced Options` toggle under settings and update the `Base URL`:
|
|
|
|
<img src="./resources/images/openhands-integration.png" height=300/>
|
|
|
|
#### **Step 2: Adjust the API Key Format**
|
|
Set the API Key using the following format:
|
|
|
|
```text
|
|
{your-llm-api-key}|invariant-auth: {your-invariant-api-key}
|
|
```
|
|
|
|
> **Note:** Do not include the curly braces `{}`.
|
|
|
|
The Invariant Proxy extracts the `invariant-auth` field from the API key and correctly forwards it to Invariant Explorer while sending the actual API key to OpenAI or Anthropic.
|
|
|
|
---
|
|
|
|
## **SWE-agent Integration**
|
|
[SWE-agent](https://github.com/SWE-agent/SWE-agent) allows your preferred language model (e.g., GPT-4o or Claude Sonnet 3.5) to autonomously utilize tools for various tasks, such as fixing issues in real GitHub repositories.
|
|
|
|
### **Using SWE-agent with Invariant Proxy**
|
|
SWE-agent does not support custom headers, so you **cannot** pass the Invariant API Key via `Invariant-Authorization`. However, **there is a workaround** using the Invariant Proxy.
|
|
|
|
#### **Step 1: Modify the API Base**
|
|
|
|
Run `sweagent` with the following flag:
|
|
|
|
```bash
|
|
--agent.model.api_base=http://localhost:8005/api/v1/proxy/{add-your-dataset-name-here}/openai
|
|
```
|
|
|
|
> **Note:** Do not include the curly braces `{}`.
|
|
|
|
#### **Step 2: Adjust the API Key Format**
|
|
Instead of setting your API Key normally, modify the environment variable as follows:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY={your-openai-api-key}|invariant-auth: {your-invariant-api-key}
|
|
export ANTHROPIC_API_KEY={your-anthropic-api-key}|invariant-auth: {your-invariant-api-key}
|
|
```
|
|
|
|
> **Note:** Do not include the curly braces `{}`.
|
|
|
|
This setup ensures that SWE-agent works seamlessly with Invariant Proxy, maintaining compatibility while enabling full functionality. 🚀
|
|
|
|
---
|
|
|
|
## **Development**
|
|
|
|
### **Run Tests**
|
|
To run tests, execute:
|
|
|
|
```bash
|
|
./run.sh tests
|
|
```
|
|
|