mirror of
https://github.com/invariantlabs-ai/invariant-gateway.git
synced 2026-07-15 06:37:18 +02:00
Update README.md
This commit is contained in:
Hemang Sarkar
@@ -1,34 +1,43 @@
|
||||
# **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.
|
||||
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 Agents** like OpenHands, SWE-agent, etc.
|
||||
- ✅ **Automatically store and organize traces** in the Invariant Explorer.
|
||||
|
||||
---
|
||||
|
||||
## **Getting Started**
|
||||
|
||||
**Run the proxy locally**
|
||||
### **Run the Proxy Locally**
|
||||
To start the Invariant Proxy, run:
|
||||
|
||||
```bash
|
||||
bash run.sh build && bash run.sh up
|
||||
```
|
||||
|
||||
This will start the Invariant Proxy on [http://localhost:8005/api/v1/proxy/](http://localhost:8005/api/v1/proxy/docs/).
|
||||
This will launch the proxy at [http://localhost:8005/api/v1/proxy/](http://localhost:8005/api/v1/proxy/docs/).
|
||||
|
||||
To integrate the Proxy with your AI agent, you’ll need to modify how your client interacts with LLM providers.
|
||||
### **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).
|
||||
|
||||
**Setup 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 will allow the Proxy to push traces to [https://explorer.invariantlabs.ai](https://explorer.invariantlabs.ai).
|
||||
---
|
||||
|
||||
**🔹 OpenAI Integration**
|
||||
## **Integration Guides**
|
||||
|
||||
2. To setup an OpenAI API key follow the steps [here](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key).
|
||||
### **🔹 OpenAI Integration**
|
||||
|
||||
3. **Modify OpenAI Client Setup**
|
||||
Instead of connecting directly to OpenAI, configure your `OpenAI` client to use the proxy.
|
||||
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
|
||||
@@ -42,16 +51,14 @@ To integrate the Proxy with your AI agent, you’ll need to modify how your clie
|
||||
),
|
||||
base_url="http://localhost:8005/api/v1/proxy/{add-your-dataset-name-here}/openai",
|
||||
)
|
||||
# If a dataset with the given name already doesn't exist in Invariant Explorer, this will create the dataset
|
||||
# before adding the traces to it.
|
||||
# Make API requests to OpenAI using the client as usual.
|
||||
```
|
||||
|
||||
**🔹 Anthropic Integration**
|
||||
> **Note:** Do not include the curly braces `{}`. If the dataset does not exist in Invariant Explorer, it will be created before adding traces.
|
||||
|
||||
2. To setup an Anthropic API key follow the steps [here](https://docs.anthropic.com/en/docs/initial-setup#set-your-api-key).
|
||||
### **🔹 Anthropic Integration**
|
||||
|
||||
3. **Modify Anthropic Client Setup**
|
||||
Instead of connecting directly to Anthropic, configure your `Anthropic` client to use the proxy.
|
||||
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
|
||||
@@ -65,70 +72,70 @@ To integrate the Proxy with your AI agent, you’ll need to modify how your clie
|
||||
),
|
||||
base_url="http://localhost:8005/api/v1/proxy/{add-your-dataset-name-here}/anthropic",
|
||||
)
|
||||
|
||||
# If a dataset with the given name already doesn't exist in Invariant Explorer, this will create the dataset
|
||||
# before adding the traces to it.
|
||||
# Make API requests to Anthropic using the client as usual.
|
||||
```
|
||||
|
||||
> **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.
|
||||
|
||||
OpenHands does not support custom headers, meaning you **cannot** pass the Invariant API Key via the `Invariant-Authorization` header directly. However, **there is a workaround** using the Invariant Proxy.
|
||||
### **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` in the modal like:
|
||||
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**
|
||||
Instead of setting your OPENAI_API_KEY (or ANTHROPIC_API_KEY) normally in the settings modal under `API Key` you will need to change the format.
|
||||
Modify the API Key format in the settings modal:
|
||||
|
||||
Updated format: ```{your-llm-api-key}|invariant-auth: {your-invariant-api-key}``` without the curly braces.
|
||||
```text
|
||||
{your-llm-api-key}|invariant-auth: {your-invariant-api-key}
|
||||
```
|
||||
|
||||
The Invariant Proxy extracts the invariant-auth field from the API key and correctly forwards the Invariant API Key, allowing traces to be pushed to Invariant Explorer. The request is correctly passed to OpenAI (or Anthropic) with the actual API Key.
|
||||
> **Note:** Do not include the curly braces `{}`.
|
||||
|
||||
This setup ensures that OpenHands works seamlessly with Invariant Proxy, maintaining compatibility while enabling full functionality. 🚀
|
||||
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:
|
||||
## **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.
|
||||
|
||||
- Fixing issues in real GitHub repositories
|
||||
- Performing tasks on the web
|
||||
- Cracking cybersecurity challenges
|
||||
- Executing custom-defined tasks
|
||||
|
||||
### Using SWE-agent with Invariant Proxy
|
||||
|
||||
SWE-agent does not support custom headers, meaning you **cannot** pass the Invariant API Key via the `Invariant-Authorization` header directly. However, **there is a workaround** using the Invariant Proxy.
|
||||
### **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**
|
||||
When running `sweagent run`, add the following flag to route requests through the Invariant Proxy:
|
||||
|
||||
Run `sweagent` with the following flag:
|
||||
|
||||
```bash
|
||||
--agent.model.api_base=http://localhost:8005/api/v1/proxy/{add-your-dataset-name-here}/openai
|
||||
```
|
||||
without the curly braces.
|
||||
|
||||
> **Note:** Do not include the curly braces `{}`.
|
||||
|
||||
#### **Step 2: Adjust the API Key Format**
|
||||
Instead of setting your OPENAI_API_KEY (or ANTHROPIC_API_KEY) normally, modify the environment variable as follows:
|
||||
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}
|
||||
```
|
||||
without the curly braces.
|
||||
|
||||
The Invariant Proxy extracts the invariant-auth field from the API key and correctly forwards the Invariant API Key, allowing traces to be pushed to Invariant Explorer. The request is correctly passed to OpenAI (or Anthropic) with the actual 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. 🚀
|
||||
|
||||
## Dev
|
||||
---
|
||||
|
||||
## **Development**
|
||||
|
||||
### **Run Tests**
|
||||
To run tests, execute:
|
||||
|
||||
### Run tests
|
||||
```bash
|
||||
./run.sh tests
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user