Quickstart

Connect an agent in about ten minutes. The examples use Gemini; OpenAI and Anthropic are further down.

1. Get an API key

Create an account, then create a key and set it in your environment:

pip install agent-supra
pip install google-genai
export AGENT_SUPRA_API_KEY="as_live_…"
export AGENT_SUPRA_URL="https://agentsupra.in"

2. Wrap your agent

Create a task with a budget, wrap your model client, and report each test run. rev is anything that changes when the code changes, such as a git commit hash or a hash of the edited files.

from google import genai
from agent_supra import Client, SupervisedRun, SupervisorPaused

sup = Client()
task = sup.create_task("Fix failing checkout tests", budget_usd=3)

with SupervisedRun(sup, task) as run:
    gemini = run.wrap_gemini(genai.Client())
    try:
        while True:
            run.check()                       # stops here once paused
            reply = gemini.models.generate_content(
                model="gemini-3.5-flash-lite", contents=prompt)
            run.tool("edit_file", apply_fix, reply.text, rev=git_rev())
            result = run.tool("run_tests", run_tests, rev=git_rev())
            run.report_tests(result.all_ids, result.failing_ids, rev=git_rev())
            if not result.failing_ids:
                run.finish("success")
                break
    except SupervisorPaused as paused:
        print("Paused:", paused.reason)       # don't retry; review it in the dashboard

3. Watch it in observation mode

New workspaces start in observation mode: runs are flagged, never paused, while you check the flags are right. Budgets and call caps are enforced from the start. When you trust the rules, turn observation mode off in Settings and add a Slack webhook so you hear about pauses.

Other model clients

# OpenAI (also works for Gemini's OpenAI-compatible endpoint)
client = run.wrap_openai(openai.OpenAI())
client.chat.completions.create(model="gpt-…", messages=[…])

# Anthropic
client = run.wrap_anthropic(anthropic.Anthropic())
client.messages.create(model="claude-…", max_tokens=1024, messages=[…])

# Anything else: record usage yourself
run.record_model_call("my-model", input_tokens=1200, output_tokens=300)

Gemini prices are built in. For other models, add prices under Settings so spend can be estimated.

Sub-agents

child = run.child() creates a run that shares the parent task's budget.

If the service is unreachable

By default the SDK fails open: your agent keeps working, events are kept in memory and sent when the service is back. Use Client(fail_mode="closed") to stop the agent instead when supervision isn't available.

What gets sent

Token counts, model names, test IDs with pass or fail, code revision IDs, and keyed fingerprints of tool arguments and errors. Prompts, replies and code are never sent. See Privacy.