> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Loop

> Braintrust's AI agent investigates your project data, creates and edits objects with your approval, and runs on a schedule when you're not watching.

<Icon icon="blend" /> **Loop** is Braintrust's AI agent. It works across your whole project, investigating logs, experiments, and datasets, and it can create and edit the objects you'd otherwise build by hand: prompts, scorers, datasets, facets, custom views, dashboards, and automations.

Loop is also the engine behind <Icon icon="scan-search" /> [**Patterns**](/docs/observe/patterns) and the <Icon icon="bug" /> [**Debugger**](/docs/observe/debug-traces), which run it on your behalf rather than through a chat.

## Start a thread

Loop runs in a Braintrust-managed runtime rather than in your browser, so it can take on longer investigations and your threads persist for you to come back to. Out of the box, it uses Braintrust's [built-in models](/docs/admin/ai-providers#available-models), which draw down your organization's monthly [model credits](/docs/plans-and-limits#model-credits), so you can start a thread without configuring an AI provider.

<Note>
  On the Starter plan, the built-in models require at least one organization owner with a work email address, or a payment method on file. See [Requirements](/docs/admin/ai-providers#requirements).
</Note>

<Steps>
  <Step title="Open Loop">
    Go to [**<Icon icon="blend" /> Loop**](https://www.braintrust.dev/app/~/loop) for the full-page experience, which gives Loop the full window and lists your saved threads. You can also start a thread from the prompt box on the project overview page, which creates the thread and opens it on the Loop page.

    Loop is embedded where you'd act on what it finds, too: the logs table, the SQL sandbox, the trace view, playgrounds, datasets, and dashboards. Each entry point opens the same agent with the current page's data already in context. For what Loop can do from any of them, see [What Loop can do](/docs/loop/capabilities).
  </Step>

  <Step title="Choose a model and reasoning effort">
    The model picker sets the model, its reasoning effort, and whether Loop runs on built-in models or your own provider. See [Choose a provider and model](#choose-a-provider-and-model).
  </Step>

  <Step title="Add context and attach files">
    Loop uses the current page's data automatically. To point it elsewhere, type `@` followed by a name to reference a dataset, experiment, project log, playground, or SQL query. When a thread has other context available, the composer also shows an **Add context** button that opens the same list to browse and search.

    To attach a file, select <Icon icon="paperclip" /> **Attach files** or drag files into the composer. Loop accepts images, audio, video, PDF, text, and JSON, up to 8 files per message, 20 MB per file, and 40 MB per message.
  </Step>

  <Step title="Ask, approve, and iterate">
    Type a question and press Enter. Loop runs read-only work without interrupting you and pauses for approval before it creates or edits anything.

    Type `/` in the composer to see the commands available in your current context, such as bootstrapping a scorer, summarizing a dataset, or filing a support ticket. The list changes depending on where you opened Loop.
  </Step>
</Steps>

<h2 id="choose-a-provider-and-model">
  Choose a provider and model
</h2>

Loop runs on three models: **GPT-5.6 Sol**, **GPT-5.6 Terra**, and **GPT-5.6 Luna**. New threads start on Sol at medium reasoning effort, which Braintrust recommends for the best results. The model picker controls:

* **Model.** Which of the three Loop runs.
* **Effort.** The reasoning effort. The available levels depend on the model, and the menu marks each model's default. Loop remembers the effort you choose for each thread.
* **Built-in.** Whether Loop runs on Braintrust's own AI providers, drawing down your monthly [model credits](/docs/plans-and-limits#model-credits), or on your own key. **Built-in** stays on and can't be turned off until you configure a provider that can serve the model you selected. After you configure that provider, Loop remembers the setting for each thread and applies your most recent choice to new threads. Once your model credits are exhausted, you can't turn **Built-in** back on, and a banner above the message box offers to upgrade.
* **Provider.** Which of your configured providers serves the model, with inference billed to that provider. This appears when **Built-in** is off and you have at least one compatible provider: OpenAI, Azure, Bedrock, or OpenRouter. Loop pins the provider you pick to that thread and selects it again when you return. For the full list, see [Models and providers](/docs/loop/manage#models-and-providers).

<Note>
  Whether members can use the built-in models is controlled by **Allow built-in models** on the [AI providers](/docs/admin/ai-providers#manage-built-in-models) page. Loop logging can also be turned off. See [Privacy](/docs/loop/manage#privacy).
</Note>

To see what a choice costs, turn on **Show turn metrics** in <Icon icon="settings-2" /> settings. The footer then shows duration, time to first token, input and output token counts, cache hit rate, and estimated turn and total cost.

## Approve changes

Every action that creates or modifies an object pauses for your approval. Each approval dialog includes a short description of the specific action, so you can see what will change before allowing it.

To skip approvals, turn on **Auto-accept edits** in **<Icon icon="settings-2" /> Settings**.

<Warning>
  Auto-accept applies to every write Loop makes in the thread, including changes that affect production, such as retagging an environment or creating an online scoring rule. Leave it off when a thread has permission to touch anything you'd want to review first.
</Warning>

## Review results in the workspace

As Loop works, results open in a workspace beside the chat. You can open anything Loop creates, edits, or references, including a pattern, prompt, scorer, facet, preprocessor, dashboard, dataset, trace, automation, or a set of experiment runs, and keep several open in tabs while the thread continues.

Hold Cmd, Ctrl, or Shift while selecting an object to open it in a new browser tab instead.

<h2 id="what-loop-cant-do">
  What Loop can't do
</h2>

Loop works inside your permissions, on one project at a time. It cannot:

* **Reach another organization's data.** A thread is scoped to the project you opened it in, and Loop resolves objects only within your organization.
* **Delete Braintrust objects.** Loop can create and update prompts, scorers, facets, preprocessors, datasets, views, and automations, but has no tool to delete them. It can delete dataset rows, and it can close a pattern, which marks the pattern inactive rather than removing it.
* **Change organization settings.** Members, permission groups, API keys, AI providers, and billing are out of reach. Loop can list and create environments for dataset versioning, but can't delete one.
* **See another user's threads.** Threads are private to the person who created them.
* **Act without approval,** unless you turn on auto-accept.
* **Change your application.** Loop works on the data and objects in Braintrust, not on your codebase or your deployments.

## Next steps

* [What Loop can do](/docs/loop/capabilities) for the full range of tasks, with example prompts.
* [Run Loop on a schedule](/docs/loop/automations) for recurring work.
* [Enable Patterns](/docs/observe/patterns/enable) to have Loop find recurring problems on its own.
* [Manage threads and limits](/docs/loop/manage) for sandbox behavior and thread cleanup.
* Try the [Loop cookbook](/docs/cookbook/recipes/Loop) for worked examples.