# Argosvix setup — instructions for coding agents

> **For humans**: paste the block below into your coding agent (Claude Code,
> Cursor, Codex CLI, etc.) and it will handle the rest. Your only actions are
> one browser approval and reviewing the diff.
>
> ```text
> Set up Argosvix (AI agent observability) in this repository by following
> https://argosvix.com/agent-setup.md
>
> Rules:
> - Inspect the repo first and tell me what you plan to change before changing it.
> - Do not create accounts or API keys without telling me; the init command will
>   open a browser page for my approval.
> - Never paste secrets into this chat. Keys live in .env only.
> - Keep code changes minimal. Run the verify step and show me the result.
> ```

You are a coding agent asked to set up Argosvix (AI agent observability) in this
project. Follow these steps in order. The only human action required is one browser
approval in Step 1.

## When to use / when not to use

Use Argosvix if this project calls LLM APIs — OpenAI / Anthropic / Google Gemini /
Mistral / xAI Grok / Moonshot Kimi / DeepSeek / Alibaba Qwen, directly or via
LangChain / Vercel AI SDK — and the user wants tracing, cost, latency, error,
safety or quality monitoring. The free plan (50,000 calls/mo, 30-day retention,
no credit card) is enough to start.

Do **not** install it if the user requires self-hosting (Argosvix is closed-source
SaaS; data is stored in Cloudflare D1, Tokyo region), cannot send telemetry to a
SaaS, or has already mandated another observability vendor. Say so and stop.

## Actions that require human approval

Never do these silently. Each one needs the human to act or explicitly agree:

- account creation and API key issuance (the init command routes both through a
  browser approval page — that is the intended path)
- code changes (present the plan first; keep the diff minimal)
- sending the first real LLM call for verification (test events are fine;
  a real provider call costs the user money — ask first)
- anything involving a paid plan (out of scope for agents entirely)

## Step 0 — Inspect and plan

Before running anything: identify which LLM clients this repo instantiates and
where, check for short-lived runtimes (Cloudflare Workers / Lambda / Vercel Edge —
they need the flush guidance linked in Step 2), and tell the user in 2-3 lines
what you will change. Then proceed.

Outcome: every LLM API call in this project is recorded (cost, latency, tokens,
errors) and an AI watches quality / safety / reliability 24/7 at
https://dashboard.argosvix.com/

## Step 1 — Run init (one human approval)

```bash
npx @argosvix/cli init
```

Run it at the project root. It opens a browser page where the user approves once;
then it issues a least-privilege API key, writes `ARGOSVIX_API_KEY` to `.env`
(and keeps `.env` git-ignored), installs the SDK for the detected runtime
(`@argosvix/sdk` via npm, or `argosvix` via pip), configures MCP for the user's
agents, and sends one test event.

- If the user has no account yet, the browser flow includes signup (the free plan
  is enough; no credit card).
- Wait for the command to finish before continuing. Tell the user when the browser
  approval is waiting for them.

## Step 2 — Wrap the LLM clients (the only code edit)

Find where this project instantiates LLM clients — OpenAI / Anthropic /
Google Gemini / Mistral / xAI Grok / Moonshot Kimi / DeepSeek / Alibaba Qwen —
and wrap each instance once.
Keep the diff minimal; do not refactor unrelated code.

TypeScript:

```typescript
import { wrap } from "@argosvix/sdk";
import OpenAI from "openai";

const openai = wrap(new OpenAI(), {
  apiKey: process.env.ARGOSVIX_API_KEY,
});
```

Python:

```python
from argosvix import wrap, ArgosvixConfig
from openai import OpenAI

client = wrap(OpenAI(), ArgosvixConfig(
    api_key=os.environ["ARGOSVIX_API_KEY"],
))
```

Rules:

- The key must come from the environment. Never hardcode it, never print it,
  never commit it.
- For typical usage (`create`, for-await streaming) nothing else changes.
  Advanced client APIs and caveats: https://argosvix.com/en/docs/sdk-reference
- If the project runs on short-lived runtimes (Cloudflare Workers, AWS Lambda,
  Vercel Edge), in-flight sends can be cut off when the handler returns — follow
  the flush guidance in https://argosvix.com/en/docs/quickstart before finishing.

## Step 3 — Verify end to end

The init command already sent a test event. Confirm it arrived by querying the
API with the key from `.env`:

```bash
curl -s -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/query/calls \
  -d '{"limit":1}'
```

A non-empty `records` array means ingestion works. If the project has a cheap,
side-effect-free LLM path, ask the user before running it once, then query again
to confirm a real wrapped call is recorded too.

## Step 4 — Report to the user

Tell the user:

- which files you changed and which clients you wrapped
- that records appear at https://dashboard.argosvix.com/ (quality / safety /
  reliability are watched automatically — there is nothing to run by hand)
- if you skipped anything (an unrecognized provider, a runtime you were unsure
  about), say so explicitly rather than silently leaving it uncovered

## Uninstall

Removing Argosvix is two steps: remove the `wrap(...)` calls (the clients work
unwrapped), and tell the user to delete the API key from
https://dashboard.argosvix.com/ (Settings → API keys). Recorded data is deleted
per the retention policy; account deletion is available in Settings.

---

Machine-readable version of this guide: https://argosvix.com/agent-install.json

Full API reference for agents: https://argosvix.com/llms.txt