> ## 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.

# Google Discovery Engine

> Trace Google Cloud Discovery Engine SDK calls in Braintrust to debug AI-powered search, answer generation, and ranking

[Google Cloud Discovery Engine](https://cloud.google.com/generative-ai-app-builder/docs/introduction) is a managed service for building AI-powered search and answer generation applications. Braintrust traces Discovery Engine calls, including generative answers, conversational search, grounding checks, and document ranking.

**Python**

## Setup

Install the Braintrust and `google-cloud-discoveryengine` packages, set your API key, and authenticate with Google Cloud. Requires Braintrust v0.41.0+ and `google-cloud-discoveryengine` v0.20.3 or later.

**1. Install packages**

```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv add braintrust google-cloud-discoveryengine
```

```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust google-cloud-discoveryengine
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url>
```

**3. Authenticate with Google Cloud**

The Discovery Engine clients load [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials). For local development, authenticate with the `gcloud` CLI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
gcloud auth application-default login
```

In production, configure Application Default Credentials for your runtime, such as an attached service account. Your credentials need permission to call Discovery Engine in the target Google Cloud project.

## Auto-instrumentation

To trace Discovery Engine calls without modifying your application code, call `braintrust.auto_instrument()` before creating your Discovery Engine clients.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

import braintrust
from google.cloud import discoveryengine_v1

braintrust.auto_instrument()
braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="discovery-engine-example",
)

client = discoveryengine_v1.RankServiceClient()
```

## Manual instrumentation

To trace a specific Discovery Engine client instance manually, use `wrap_google_discoveryengine()`. Use this when you want to instrument a particular client rather than patching all Discovery Engine clients globally.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

import braintrust
from braintrust.integrations.google_discoveryengine import wrap_google_discoveryengine
from google.cloud import discoveryengine_v1

braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="discovery-engine-example",
)

client = wrap_google_discoveryengine(discoveryengine_v1.RankServiceClient())
```

## What Braintrust traces

Braintrust instruments synchronous and asynchronous `google-cloud-discoveryengine` v1 clients and creates spans per call:

* Answer query spans (`google_discoveryengine.answer_query`), with the query and optional preamble as input, answer text, citations, references, and grounding details as output, and time-to-first-token for streaming.
* Streaming answer query spans (`google_discoveryengine.stream_answer_query`), with the same structure as non-streaming answer queries, with incremental output aggregated across chunks.
* Conversational search spans (`google_discoveryengine.converse_conversation`), with the query as input and the summary text with citations and references as output.
* Grounding check spans (`google_discoveryengine.check_grounding`), with the answer candidate and grounding facts as input and support score, cited chunks, and claims as output.
* Ranking spans (`google_discoveryengine.rank`), with query and document records as input, up to 100 ranked results with scores as output, and ranking configuration and model as metadata when specified.
* Provider metadata and the model and serving configuration supplied with generation requests.
* Errors captured on every call.

> [!NOTE]
>
> Asynchronous mode `answer_query` calls (where `asynchronous_mode=True` in the request) are not traced and pass through unmodified. This is separate from using an asynchronous Python client, which is supported.

## Resources

* [Google Cloud Discovery Engine Python SDK](https://cloud.google.com/python/docs/reference/discoveryengine/latest).
* [Discovery Engine documentation](https://cloud.google.com/generative-ai-app-builder/docs/introduction).


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