> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/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.

&#x20;**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. With a [connected GitHub repository](https://docs.braintrust.dev/loop/github.md), it can fix code and open pull requests for review.

Loop also powers  [**Patterns**](https://docs.braintrust.dev/observe/patterns.md), which investigates on your behalf without a chat.

> [!NOTE]
>
> On BYOC, Loop runtime availability depends on your deployment environment and region. See [BYOC Loop availability](https://docs.braintrust.dev/admin/deployment/byoc/manage.md#loop-availability).

## Start a thread

You can start without configuring an AI provider. Loop offers [built-in models](https://docs.braintrust.dev/admin/ai-providers.md#available-models) billed against your organization's monthly [model credits](https://docs.braintrust.dev/plans-and-limits.md#model-credits) and saves threads for you to return to.

> [!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](https://docs.braintrust.dev/admin/ai-providers.md#requirements).

1. Go to [** Loop**](https://www.braintrust.dev/app/~/loop) and start a thread.
2. Add context with `@` followed by a dataset, experiment, project log, playground, or SQL query name. When available, **Add context** opens the same list.
3. Optionally, attach files with  **Attach files**, drag them into the composer, or paste an image. Loop accepts images, audio, video, PDF, text, and JSON, up to 8 files per message, 20 MB per file, and 40 MB total.
4. Type your question and press Enter. Review and approve any proposed changes, then ask follow-up questions. Messages sent while Loop works queue until the turn finishes.

Loop starts with **Auto** on, using your organization's default provider and its recommended model and reasoning effort. To override them, use the [model picker](#choose-a-provider-and-model).

You can also start from the project overview's prompt box or open Loop from logs, Query, traces, playgrounds, datasets, Patterns, dashboards, and the chart editor. Loop includes that page's data as context. See [What Loop can do](https://docs.braintrust.dev/loop.md).

Type `/` at the start of a message or after whitespace to see commands, such as creating a scorer or summarizing a dataset. Available commands depend on where you opened Loop.

## Choose a provider and model

New threads start with **Auto** on. Auto follows your organization's [default provider](https://docs.braintrust.dev/admin/organizations.md#set-a-default-provider-for-loop) and uses its recommended model and reasoning effort. The recommended model is GPT-6.1 Sol when the provider serves it. Use the model picker to choose:

* **Auto.** Choosing a model, effort, or provider turns off **Auto** for that thread. Turn it back on to follow the default again. If no default is set or the default is unavailable, you can't turn on **Auto**, and its tooltip explains why.
* **Model.** GPT-6 Astra, GPT-6 Luna, GPT-6.1 Sol, GPT-6 Sol, GPT-5.6 Sol, GPT-5.6 Terra, or GPT-5.6 Luna. Configuring a provider such as Anthropic or Bedrock doesn't add Claude or other models to this list. You can still use Claude in [prompts](https://docs.braintrust.dev/evaluate/prompts.md), [playgrounds](https://docs.braintrust.dev/evaluate/playgrounds.md), and [LLM-as-a-judge scorers](https://docs.braintrust.dev/evaluate/llm-as-a-judge.md).
* **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, Databricks, and OpenRouter. Loop remembers your choice for each thread. See [Models and providers](https://docs.braintrust.dev/loop/manage.md#models-and-providers) for the full list and how new threads choose a provider.

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

* **Access.** **Allow built-in models** under ** Settings** > [** Models**](https://www.braintrust.dev/app/~/configuration/models/organization) 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. If **Auto** is on and your default provider is **Braintrust**, the model picker shows "Default unavailable". Turn off **Auto** and choose a configured provider to keep working.

To monitor usage, turn on **Show turn metrics** in  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 a Braintrust object, Loop describes the action and asks for your approval. For external MCP tools, approval depends on the server's tool annotations and your approval settings.

In a [shared thread](https://docs.braintrust.dev/loop/manage.md#share-a-thread), Loop accesses Braintrust using the sender's permissions. Only the sender can approve or cancel the work their message starts.

To skip approvals for tools that support it, turn on **Auto-accept edits** in ** Settings**. Some actions still require explicit approval.

> [!WARNING]
>
> Auto-accept can allow production changes, such as retagging an environment or creating an online scoring rule. Leave it off if you need to review those changes first.

## Review results in the workspace

Results open in tabs beside the chat. You can keep several objects open while Loop works, including anything it creates, edits, or references.

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

## What Loop can't do

Loop accesses Braintrust one project at a time, within your existing UI and API permissions. External MCP calls use the [project's shared credentials](https://docs.braintrust.dev/loop/mcp.md#manage-shared-access). Loop cannot:

* **Reach another Braintrust 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](https://docs.braintrust.dev/loop/manage.md#share-a-thread).
* **Run tools that require approval in an interactive thread** unless you approve them or enable auto-accept. [Scheduled runs](https://docs.braintrust.dev/loop/automations.md#write-tool-permissions) use separate permission rules.

Connected MCP tools can act on external systems within the shared credential's permissions, including making changes if the server exposes tools for them.

## Next steps

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.