Getting Started With Explorer

Learn how to upload your AI agent traces to the Invariant Explorer

This quickstart guide will walk you through the process of setting up the Invariant SDK to upload your AI agent traces to the Invariant Explorer.

You can use Explorer to visualize, analyze, and collaborate on your AI agent traces, as well as compare them with other agents and models.

Viewing agent traces in Explorer

1. Create an Explorer Account

First, navigate to the Invariant Explorer and create an account via GitHub Sign-In.

If you prefer to keep your data local, you can also self-host Explorer on your own infrastructure.

2. Create an API Key

Once you have created an account, go to your User Settings and generate an API key.

Make note of your API key, as you will need it to authenticate your uploads. If you're running in a shell, you can export the API key now as an environment variable:

export INVARIANT_API_KEY=<your-api-key>

3. Install the Invariant SDK

Next, install the Invariant SDK in your Python environment, by running the following command. See Installation for alternative methods using different package managers.

pip install invariant-sdk

Self-Host Note that for the self-hosted version of Explorer, you will need to configure the SDK to point to your custom endpoint.

4. Prepare Your Traces and Upload

Now, you can start preparing your AI agent traces for upload. The Invariant SDK then provides a Client class that you can use to upload your traces in an Invariant-compatible format:

from invariant_sdk.client import Client

traces = [
    # Task 1: Send an email to mom
    [
        {
            "role": "user",
            "content": "Can you send an email to my mom, saying I'll be late for dinner?",
        },
        {
            "role": "assistant",
            "content": "Sending an email to your mom now.",
            "tool_calls": [
                {
                    "type": "function",
                    "function": {
                        "name": "send_email",
                        "arguments": {
                            "to": "mom@mail.com",
                            "subject": "Running late, sorry!",
                        }
                    }
                }
            ]
        }
    ]
]

client = Client()
client.create_request_and_push_trace(traces, dataset="my-first-dataset")

This will upload your traces to the Invariant Explorer under a new dataset named my-first-dataset. If the corresponding dataset already exists, the traces will be appended to it.

To learn more about the expected trace format see the chapter on the trace format requirements.

Work With Your Traces in Explorer

You can now navigate to the following URL to view your uploaded traces:

https://explorer.invariantlabs.ai/<your_username>/my-first-dataset/t/1

You can also use the Invariant Explorer to analyze your traces, compare them with other agents, and collaborate with your team.

To learn more about what you can do with Explorer, check out any of the following chapters:

Benchmarks → Submit your AI agent to the Invariant benchmark registry for comparison Trace Format → Learn about the Invariant trace format and how to structure your traces for ingestion Client Setup → Setting up endpoints and authentication for the Invariant SDK Pushing Traces → Learn about traces, datasets and annotations.