From c9d5bafd8ae48c5ffc6df42b3046e8c72113950f Mon Sep 17 00:00:00 2001 From: Hemang Sarkar Date: Tue, 18 Feb 2025 11:59:35 +0100 Subject: [PATCH] Update README.md --- README.md | 99 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 53 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index be2c829..1ad0f1f 100644 --- a/README.md +++ b/README.md @@ -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. ![Invariant Proxy Diagram](resources/images/invariant-proxy.png) +--- + ## **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`: - #### **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 ``` +