> ## 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 for investigating logs, experiments, and datasets across your project. It can also create and edit prompts, scorers, datasets, facets, custom views, dashboards, and automations.

Loop also powers <Icon icon="scan-search" /> [**Patterns**](/docs/observe/patterns) and the <Icon icon="bug" /> [**Debugger**](/docs/observe/debug-traces), which investigate on your behalf without a chat.

## Start a thread

Loop runs in a Braintrust-managed runtime, supporting long investigations and saving threads for you to return to. You can start without configuring an AI provider: Loop uses [built-in models](/docs/admin/ai-providers#available-models) billed against your organization's monthly [model credits](/docs/plans-and-limits#model-credits).

<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) to start a thread or return to a saved one. Starting from the prompt box on the project overview page also opens your thread on the Loop page.

    You can also open Loop from the logs table, SQL sandbox, trace view, playgrounds, datasets, and dashboards. Each opens the same agent with the page's data in context. See [What Loop can do](/docs/loop/capabilities).
  </Step>

  <Step title="Choose a model and reasoning effort">
    Use the model picker to [choose a model, reasoning effort, and provider](#choose-a-provider-and-model).
  </Step>

  <Step title="Add context and attach files">
    Type `@` followed by a name to reference a dataset, experiment, project log, playground, or SQL query. When other context is available, **Add context** opens the same list to browse and search.

    Select <Icon icon="paperclip" /> **Attach files** or drag files into the composer. Loop accepts images, audio, video, PDF, text, and JSON, with these limits:

    * 8 files per message.
    * 20 MB per file.
    * 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 `/` at the start of your message or after whitespace to see available commands. Depending on where you opened Loop, you can bootstrap a scorer, summarize a dataset, or file a support ticket.
  </Step>
</Steps>

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

New threads start on GPT-5.6 Sol at medium reasoning effort, Braintrust's recommended setting. Use the model picker to choose:

* **Model.** GPT-6 Astra, GPT-6 Luna, GPT-6 Sol, GPT-5.6 Sol, GPT-5.6 Terra, or GPT-5.6 Luna.
* **Effort.** Available levels depend on the model, and the menu marks its default. Loop remembers your choice for each thread.
* **Provider.** Select **Braintrust** to use model credits, or a configured provider to bill inference to that provider. Supported providers include OpenAI, Azure, Bedrock, and OpenRouter. Loop remembers your choice for each thread and uses your most recent choice for new threads. See [Models and providers](/docs/loop/manage#models-and-providers) for the full list.

Provider access and usage depend on your organization's settings and credits:

* **Access.** **Allow built-in models** on the [AI providers](/docs/admin/ai-providers#manage-built-in-models) page controls whether members can select **Braintrust**.
* **Credits.** When model credits run out, **Braintrust** becomes unavailable and a banner above the message box offers an upgrade.
* **Logging.** Loop logging can be turned off. See [Privacy](/docs/loop/manage#privacy).

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

## Approve changes

Before creating or modifying an object, Loop describes the action and asks for your approval.

In a [shared thread](/docs/loop/manage#share-a-thread), Loop responds to each message using the sender's permissions. Only that sender can approve or cancel the work their message starts.

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

<Warning>
  Auto-accept applies to every write in the thread, including production changes such as retagging an environment or creating an online scoring rule. Leave it off if you need to review those changes first.
</Warning>

## Review results in the workspace

Results open in a workspace beside the chat. Keep several objects open in tabs while Loop works, including patterns, prompts, scorers, facets, preprocessors, dashboards, datasets, traces, automations, and experiment runs. You can open anything Loop creates, edits, or references.

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 on one project at a time, within your existing UI and API permissions. 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 cannot delete them. It can delete dataset rows or close a pattern, marking it inactive rather than removing it.
* **Change organization settings.** Loop cannot manage members, permission groups, API keys, AI providers, or billing. It can list and create environments for dataset versioning, but cannot delete them.
* **Access someone else's private threads.** Threads are private by default. Owners can [share threads with project members](/docs/loop/manage#share-a-thread).
* **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.