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

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

<View title="Python" icon="/images/sdk-icons/python.svg">
  <h2 id="setup-python">
    Setup
  </h2>

  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.

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```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
        ```
      </CodeGroup>
    </Step>

    <Step title="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>
      ```
    </Step>

    <Step title="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.
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-python">
    Auto-instrumentation
  </h2>

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

  <CodeGroup>
    ```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()
    ```
  </CodeGroup>

  <h2 id="manual-instrumentation-python">
    Manual instrumentation
  </h2>

  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.

  <CodeGroup>
    ```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())
    ```
  </CodeGroup>

  <h2 id="what-traced-python">
    What Braintrust traces
  </h2>

  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.
  </Note>

  <h2 id="resources-python">
    Resources
  </h2>

  * [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).
</View>