{% extends "base.html" %}
{% block title %}Quickstart | {{ app_name }}{% endblock %}
{% block body_class %}landing{% endblock %}
{% block body %}
<header><div class="wrap">
  <a class="brand" href="/"><span class="brand-mark" aria-hidden="true"></span>{{ app_name }}</a>
  <nav aria-label="Main">{% if session %}<a class="btn" href="/app">Open dashboard</a>{% else %}<a href="/login">Log in</a>{% endif %}</nav>
</div></header>
<main class="wrap prose doc">
  <h1>Quickstart</h1>
  <p class="muted">Create a first run in a few minutes, then connect your agent. Gemini, OpenAI and Anthropic are supported.</p>
  <p>Using Claude Code? The <a href="https://github.com/voidpusher/agent-supra/blob/main/docs/claude-code.md">experimental hook integration</a> connects tool activity and pytest reports. It requires the current source package and does not measure model spend.</p>
  <p>For an existing command, <a href="https://github.com/voidpusher/agent-supra/blob/main/docs/cli-watch.md">CLI watch</a> tracks process exits and JUnit reports without changing the agent loop. Enforcement cancels the owned process tree; model spend is not measured.</p>
  <p>The <a href="https://github.com/voidpusher/agent-supra/blob/main/docs/provider-proxy.md">local provider proxy</a> adds Chat Completions token usage and estimated-spend checks. One in-flight request can exceed an estimated budget.</p>

  <h2>1. Get an API key</h2>
  <p>{% if session %}<a href="/app/keys">Create a key</a>{% else %}<a href="/signup">Create an account</a>, then create a key{% endif %} and set it in your environment:</p>
<pre class="snippet">pip install agent-supra
export AGENT_SUPRA_API_KEY="as_live_…"
export AGENT_SUPRA_URL="{{ base_url }}"</pre>
  <p>On Windows PowerShell, use <code>$env:AGENT_SUPRA_API_KEY="as_live_…"</code> and <code>$env:AGENT_SUPRA_URL="{{ base_url }}"</code> instead of <code>export</code>.</p>

  <h2>2. Verify your first run</h2>
  <p>Save this as <code>first_run.py</code> and run <code>python first_run.py</code>. It needs only your Agent Supra key and should show a completed run in your dashboard.</p>
<pre class="snippet">from agent_supra import Client, SupervisedRun

sup = Client()
task = sup.create_task("First Agent Supra run")
with SupervisedRun(sup, task) as run:
    run.report_tests(["smoke"], [], rev="first-run")
    run.finish("success")
    print("Completed run:", run.run_id)</pre>

  <h2>3. Wrap your agent</h2>
  <p>Install <code>google-genai</code> and set <code>GEMINI_API_KEY</code> for Gemini. The following is an integration outline: replace <code>prompt</code>, <code>apply_fix</code>, <code>run_tests</code> and <code>git_rev</code> with your agent's own functions. <code>rev</code> 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 <a href="https://github.com/voidpusher/agent-supra/blob/main/examples/gemini_agent.py">gemini_agent.py</a>.</p>
<pre class="snippet">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</pre>

  <h2>4. Watch it in observation mode</h2>
  <p>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 <a href="/app/settings">Settings</a> and add a Slack webhook so you hear about pauses.</p>

  <h2>Other model clients</h2>
<pre class="snippet"># 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)</pre>
  <p>Gemini prices are built in. For other models, add prices under <a href="/app/settings">Settings</a> so spend can be estimated.</p>

  <h2>Sub-agents</h2>
  <p><code>child = run.child()</code> creates a run that shares the parent task's budget.</p>

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

  <h2>What gets sent</h2>
  <p>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 <a href="/privacy">Privacy</a>.</p>
  <h2>Help improve detection</h2>
  <p>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.</p>
  <p>Found something that does not match this guide? <a href="https://github.com/voidpusher/agent-supra/issues">Report it on GitHub</a> 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.</p>
</main>
{% endblock %}