{% extends "base.html" %} {% block title %}Quickstart | {{ app_name }}{% endblock %} {% block body_class %}landing{% endblock %} {% block body %}
{{ app_name }}

Quickstart

Create a first run in a few minutes, then connect your agent. Gemini, OpenAI and Anthropic are supported.

Using Claude Code? The experimental hook integration connects tool activity and pytest reports. Install Agent Supra 1.4.0 or newer for automatic pytest, Vitest and Jest reports and estimated model spend.

Using Codex? Run agent-supra codex-setup with Agent Supra 1.5.0 or newer, then trust the hooks in Codex. See the Codex integration.

For an existing command, CLI watch tracks process exits and JUnit reports without changing the agent loop. Enforcement cancels the owned process tree; model spend is not measured.

The local provider proxy adds Chat Completions token usage and estimated-spend checks. One in-flight request can exceed an estimated budget.

1. Get an API key

{% if session %}Create a key{% else %}Create an account, then create a key{% endif %} and set it in your environment:

python -m pip install --upgrade "agent-supra>=1.1.0"
read -rs -p "Agent Supra API key: " AGENT_SUPRA_API_KEY; printf '\n'
export AGENT_SUPRA_API_KEY
export AGENT_SUPRA_URL="{{ base_url }}"

The commands above use Bash. Paste your key at the hidden prompt, so it stays out of shell history. On Windows PowerShell, run the same install command, then:

$env:AGENT_SUPRA_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host 'Agent Supra API key' -AsSecureString)).Password
$env:AGENT_SUPRA_URL = '{{ base_url }}'

2. Verify your first run

Save this as first_run.py and run python first_run.py. This connection check needs only your Agent Supra key, makes no model calls, and verifies that the server received a completed run. It is not a real-agent test.

from agent_supra import Client, SupervisedRun

sup = Client(fail_mode="closed")
sup.whoami()  # check authentication before creating anything
task = sup.create_task("Connection check", policy={"observation_mode": True})
with SupervisedRun(sup, task) as run:
    run.report_tests(["smoke"], [], rev="first-run")
    run.finish("success")

status = sup.decide(run.run_id)
if status.get("degraded") or status.get("state") != "completed":
    raise RuntimeError("Run not verified. Check your connection and dashboard.")
print("Verified completed run:", run.run_id)

Open the run in your dashboard. A 401 or 403 means the key needs attention; recreate a revoked key under API keys. A connection error can mean the URL is wrong or the service is unavailable. A browser login does not set your terminal's API key.

3. Wrap your agent

Install google-genai and set GEMINI_API_KEY for Gemini. The following is an integration outline: replace prompt, apply_fix, run_tests and git_rev with your agent's own functions. rev should change when the code changes, such as a git commit hash or a hash of edited files. For a runnable end-to-end example, see gemini_agent.py.

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

4. 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.

Help improve detection

Joining the setup trial? Follow the participant guide and connect one of your own agents after this connection check.

Open a run in your dashboard and rate each flag as Useful, Too early or False alarm. If a run looked stuck but Supra missed it, use Report a missed loop on that run. Feedback does not pause, continue or stop the agent. Workspace members can update a flag's verdict.

Found something that does not match this guide? Report it on GitHub or use the contact link below. Include the run ID and the step that blocked setup. Keep API keys, prompts and private code out of public issues.

{% endblock %}