# Ambral > ## Agent Instructions > To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets. - [Introduction](https://docs.ambral.ai/index.md): Ambral helps you pick the best model for each of your agents, by cost, quality, or latency, measured on your own production traffic. - [Quickstart](https://docs.ambral.ai/quickstart.md): Install the Ambral skill, ask your coding agent to connect your app, and see your first trace. - [Concepts](https://docs.ambral.ai/concepts.md): Replay runs and offline runs, and the primitives Ambral is built from: workloads, sessions, traces, tasksets, scoring configs and runs. - [Connect an agent](https://docs.ambral.ai/guides/connect-an-agent.md): Point your agent's model client at the Gateway, so each of its sessions is recorded as a trace under a workload. - [Shadow evals](https://docs.ambral.ai/guides/shadow-evals.md): A shadow eval, also called a replay eval, replays your agent's recorded sessions to candidate models and scores each reply. - [Build and run a replay eval](https://docs.ambral.ai/guides/replay-evals.md): Build a taskset from your agent's recorded traces, set how its replies are scored, run candidate models on it, and read the results. - [How replay scoring works](https://docs.ambral.ai/guides/scoring.md): How a scoring config picks the points a run replays, scores each reply, and turns those scores into each trace's. - [A support agent in a live chat](https://docs.ambral.ai/examples/chat-agent.md): Match the baseline turn by turn, keep to a policy it must never break, and hand to a person what the policy says to. - [A coding agent](https://docs.ambral.ai/examples/coding-agent.md): Judge the path, with rules that must hold at every reply. - [A research agent](https://docs.ambral.ai/examples/research-agent.md): Judge the path and the report, half each. - [A retrieval agent](https://docs.ambral.ai/examples/retrieval.md): Grade the answer, not how it got there, and cheaply. - [An agent that writes records](https://docs.ambral.ai/examples/state-writes.md): Grade only the moments that change something, each message to the tenant and each write to the record, and don't let a model pass by never making them. It is one targeted run beside the workload's main scoring, not all of it. - [A support agent working tickets](https://docs.ambral.ai/examples/ticket-agent.md): Judge the session by what it did, weigh a missed escalation over an extra one, and check each action call's fields. - [An agent with destructive tools](https://docs.ambral.ai/examples/tool-safety.md): One rule at every reply that must never fail. - [Report your own offline suite](https://docs.ambral.ai/guides/offline-evals.md): Keep running your own eval suite where it runs today, and report each time it runs to Ambral as an offline run. - [Report and read an offline run](https://docs.ambral.ai/guides/offline-runs.md): Wire your suite to report each time it runs, check its first run, and read its runs across commits and models. - [What a result holds](https://docs.ambral.ai/guides/offline-results.md): What a suite reports of each scenario of an offline run, and the environment the SDKs read. - [The ambral CLI](https://docs.ambral.ai/cli/index.md): Run it, sign in, choose the org it acts in, read its output from a script, and install the skill. - [Global flags](https://docs.ambral.ai/cli/reference/global-flags.md): The flags ambral adds to every command. - [ambral login](https://docs.ambral.ai/cli/reference/login.md): Sign in through the browser, approving the sign-in on Ambral's /device page - [ambral logout](https://docs.ambral.ai/cli/reference/logout.md): Sign out: end this CLI's session on the server and forget it - [ambral whoami](https://docs.ambral.ai/cli/reference/whoami.md): Show the account this CLI is signed in as, the Ambral address, and the org it acts in - [ambral orgs](https://docs.ambral.ai/cli/reference/orgs.md): List your orgs, create one, and link this project to one - [ambral models](https://docs.ambral.ai/cli/reference/models.md): List the models workloads can serve - [ambral workloads](https://docs.ambral.ai/cli/reference/workloads.md): Create, list and show the org's workloads, retitle and relabel them, change their model pools, and choose the model that serves each - [ambral traces](https://docs.ambral.ai/cli/reference/traces.md): List and read the org's recorded sessions - [ambral tasksets](https://docs.ambral.ai/cli/reference/tasksets.md): Create and read a workload's tasksets, line their runs up by run or by model, set how they're scored, and read the prompts their traces open with - [ambral prompts](https://docs.ambral.ai/cli/reference/prompts.md): Put and read the system prompts to score models under, each by its pr_… id - [ambral runs](https://docs.ambral.ai/cli/reference/runs.md): Start score runs of a taskset, read what they found, rescore those that completed, cancel those still running, and resume those cancelled - [ambral keys](https://docs.ambral.ai/cli/reference/keys.md): List the org's API keys - [ambral skill](https://docs.ambral.ai/cli/reference/skill.md): Install the skill that teaches a coding agent to use ambral - [TypeScript: @ambral/evals](https://docs.ambral.ai/sdks/typescript.md): Report a Vitest suite, a script or another test runner to Ambral as an offline run. - [Python: ambral-evals](https://docs.ambral.ai/sdks/python.md): Report a pytest suite, a script, a verifiers eval or a Harbor job to Ambral as an offline run. - [API overview](https://docs.ambral.ai/api-reference/index.md): Ambral's two HTTP APIs: the hosts that serve them, the key they take, the x-ambral-eval header, rate limits and errors. - [Create a chat completion](https://docs.ambral.ai/api-reference/inference/create-a-chat-completion.md): OpenAI's Chat Completions API. `model` is `ambral/auto` with an `x-workload` header (or `ambral/auto:`), which serves the workload's primary model and records the call to its traces. The answer is in Chat Completions' own response schema, with `id` the call's own id, `model` the model that… - [List models](https://docs.ambral.ai/api-reference/inference/list-models.md): Lists `ambral/auto`, the model every request names, in the shape OpenAI's SDKs and model pickers read. - [Create a message](https://docs.ambral.ai/api-reference/messages/create-a-message.md): Anthropic's Messages API. `model` is `ambral/auto` with an `x-workload` header (or `ambral/auto:`), which serves the workload's primary model and records the call to its traces. The answer is in the Messages API's own response schema, with `id` the call's own id, `model` the model that ser… - [Open an offline run](https://docs.ambral.ai/api-reference/runs/open-an-offline-run.md): Of a suite's taskset, `/`, on `model`, any of the workload's pool (`RunSubjectNotInPool` when it isn't), or the workload's primary when it names none. The workload must exist (`WorkloadNotFound`); its first run of a taskset by that name creates it, and a replay taskset's name is `… - [Report scenarios to an offline run](https://docs.ambral.ai/api-reference/runs/report-scenarios-to-an-offline-run.md): 1 to 100 reports, each one run of a scenario as the harness scored it, stored in one transaction. Answers one result per report, in the order sent: stored, with its trace and its repeat, the run of its scenario it is, from 0; or refused, with a `code`, a sentence, and the bound it broke, if one did,… - [Close an offline run](https://docs.ambral.ai/api-reference/runs/close-an-offline-run.md): Closes the run for `opener`, the opener its open answered (`OfflineRunOpenerNotFound` for another), once the reports in flight are stored. The last of its openers to close completes it, and it takes no more reports until one opens it again by its key; its result is stored on it as it completes. Clos… ## OpenAPI Specs - [gateway](/api-reference/gateway.json) - [report](/api-reference/report.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.