> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/_mcp/server.

# Vertex AI (tracing)

> Trace Vertex AI SDK calls with Respan.

[Vertex AI](https://cloud.google.com/vertex-ai) is Google Cloud's managed platform for foundation models, including Gemini and third-party models. Respan captures Vertex AI generation, streaming, chat, prompt, completion, token, and workflow spans.

This tracing setup uses your Google Cloud credentials directly. To route requests through Respan instead, use the [Vertex AI gateway setup](/docs/gateway/vertex-ai).

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/api/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [Vertex AI gateway setup](/docs/gateway/vertex-ai) to route calls through the Respan gateway.

#### Example projects

* [Example projects root](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

```bash Python
pip install respan-ai respan-instrumentation-vertexai google-cloud-aiplatform
```

```bash TypeScript
npm install @respan/respan @respan/instrumentation-vertexai @google-cloud/vertexai
```

#### Set environment variables

```bash
export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/gcp-key.json"
export GOOGLE_CLOUD_PROJECT="your-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

Google Cloud credentials are used for Vertex AI requests. `RESPAN_API_KEY` exports traces to Respan.

#### Initialize and run

```python Python
import vertexai
from vertexai.generative_models import GenerativeModel
from respan import Respan
from respan_instrumentation_vertexai import VertexAIInstrumentor

respan = Respan(instrumentations=[VertexAIInstrumentor()])

vertexai.init(project="your-gcp-project", location="us-central1")

model = GenerativeModel("gemini-2.0-flash")
response = model.generate_content("Say hello in three languages.")
print(response.text)
```

```typescript TypeScript
import { VertexAI } from "@google-cloud/vertexai";
import { Respan } from "@respan/respan";
import { VertexAIInstrumentor } from "@respan/instrumentation-vertexai";

const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL,
  instrumentations: [new VertexAIInstrumentor()],
});
await respan.initialize();

const vertexAI = new VertexAI({
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION ?? "us-central1",
});
const model = vertexAI.getGenerativeModel({ model: "gemini-2.0-flash" });

await respan.withWorkflow({ name: "vertexai_generate_content_example" }, async () => {
  const result = await model.generateContent("Say hello in one sentence.");
  console.log(result.response.candidates?.[0]?.content?.parts?.[0]?.text);
});

```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see Vertex AI generate-content, streaming, and chat spans.

## Configuration

| Parameter              | Type                                  | Default           | Description                                                                                     |
| ---------------------- | ------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| `api_key` / `apiKey`   | `str \| None` / `string \| undefined` | `RESPAN_API_KEY`  | Respan API key used to export traces.                                                           |
| `base_url` / `baseURL` | `str \| None` / `string \| undefined` | `RESPAN_BASE_URL` | Optional Respan trace export API URL.                                                           |
| `instrumentations`     | `list` / `RespanInstrumentation[]`    | `[]`              | Include `VertexAIInstrumentor()` or `new VertexAIInstrumentor()` to activate Vertex AI tracing. |

## Attributes

### In Respan()

Set defaults at initialization. These apply to all spans.

```python Python
from respan import Respan
from respan_instrumentation_vertexai import VertexAIInstrumentor

respan = Respan(
    instrumentations=[VertexAIInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "vertex-api", "version": "1.0.0"},
)
```

```typescript TypeScript
import { Respan } from "@respan/respan";
import { VertexAIInstrumentor } from "@respan/instrumentation-vertexai";

// Note: default attributes are set via propagateAttributes() in TypeScript.
const respan = new Respan({
  instrumentations: [new VertexAIInstrumentor()],
});
```

### With propagate\_attributes

Override per-request attributes using a context scope.

```python Python
from respan import Respan, propagate_attributes
from respan_instrumentation_vertexai import VertexAIInstrumentor

respan = Respan(instrumentations=[VertexAIInstrumentor()])

async def handle_request(user_id: str, question: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        response = model.generate_content(question)
        print(response.text)
```

```typescript TypeScript
import { Respan } from "@respan/respan";
import { VertexAIInstrumentor } from "@respan/instrumentation-vertexai";

const respan = new Respan({
  instrumentations: [new VertexAIInstrumentor()],
});
await respan.initialize();

async function handleRequest(userId: string, question: string) {
  await respan.propagateAttributes(
    {
      customer_identifier: userId,
      thread_identifier: "conv_abc_123",
      metadata: { plan: "pro" },
    },
    async () => {
      const result = await model.generateContent(question);
      console.log(result.response.candidates?.[0]?.content?.parts?.[0]?.text);
    }
  );
}
```

| Attribute             | Type                               | Description                                  |
| --------------------- | ---------------------------------- | -------------------------------------------- |
| `customer_identifier` | `str` / `string`                   | Identifies the end user in Respan analytics. |
| `thread_identifier`   | `str` / `string`                   | Groups related messages into a conversation. |
| `metadata`            | `dict` / `Record<string, unknown>` | Custom key-value pairs.                      |

## Captured operations

* `GenerativeModel.generateContent()`
* `GenerativeModel.generateContentStream()`
* `ChatSession.sendMessage()`
* `ChatSession.sendMessageStream()`