Skip to main content

Trace Vertex AI requests

Trace Gemini requests on Vertex AI in Future AGI using the Google Gen AI SDK.

Choose the SDK

For new applications, use traceAI-google-genai with google-genai. Its GoogleGenAIInstrumentor wraps the SDK's synchronous and asynchronous generation and streaming methods, including clients configured with vertexai=True.

traceAI-vertexai is the legacy integration for google-cloud-aiplatform. Google deprecated its generative AI modules, including vertexai.generative_models, and announced their removal after June 24, 2026. This package supports google-cloud-aiplatform>=1.61.0,<=1.101.0; the lower bound allows the protobuf version required by the tracing dependencies, and the upper bound retains a release containing those modules. It does not instrument google-genai. Do not install the separate vertexai distribution to set up either route.

Install the maintained instrumentation package and SDK:

pip install traceAI-google-genai google-genai

You need a Google Cloud project with Vertex AI enabled, access to your chosen model in the selected location, and Application Default Credentials. For local development:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_MODEL="your-enabled-model-id"
export FI_API_KEY="your-future-agi-api-key"
export FI_SECRET_KEY="your-future-agi-secret-key"

Use a model ID available to your project and location. In a deployed application, use its service account or another supported Application Default Credentials configuration instead of an interactive login.

Register the tracer and instrument the SDK before making requests:

import os

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from google import genai
from traceai_google_genai import GoogleGenAIInstrumentor


def main():
    trace_provider = register(
        project_type=ProjectType.OBSERVE,
        project_name="vertexai_app",
    )
    GoogleGenAIInstrumentor().instrument(tracer_provider=trace_provider)
    try:
        client = genai.Client(
            vertexai=True,
            project=os.environ["GOOGLE_CLOUD_PROJECT"],
            location=os.environ.get("GOOGLE_CLOUD_LOCATION", "global"),
        )
        response = client.models.generate_content(
            model=os.environ["GOOGLE_GENAI_MODEL"],
            contents="Write a haiku about a mountain trail.",
        )
        print(response.text)
    finally:
        trace_provider.force_flush()


if __name__ == "__main__":
    main()

This example is also available as examples/google_genai_vertex.py. Open the vertexai_app project in Future AGI Observe to inspect the generation span, input, output and token usage returned by the SDK.

Keep an existing legacy application running

For applications that still import vertexai.generative_models, install the bounded legacy dependency rather than upgrading it past the supported range:

pip install traceAI-vertexai 'google-cloud-aiplatform==1.101.0'

Use the same Google Cloud and Future AGI credentials above, but select a region where your model is available. Older supported legacy SDKs reject global; if you set it for the recommended route, override it before running the legacy example:

export GOOGLE_CLOUD_LOCATION="us-central1"

The legacy example defaults to us-central1 when the variable is unset. Instrument before importing vertexai so the legacy SDK's GAPIC clients are wrapped when they are created:

import os

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_vertexai import VertexAIInstrumentor

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="vertexai_legacy_app",
)
VertexAIInstrumentor().instrument(tracer_provider=trace_provider)

import vertexai
from vertexai.generative_models import GenerativeModel

vertexai.init(
    project=os.environ["GOOGLE_CLOUD_PROJECT"],
    location=os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1"),
)
try:
    response = GenerativeModel(os.environ["GOOGLE_GENAI_MODEL"]).generate_content(
        "Write a haiku about a mountain trail."
    )
    print(response.text)
finally:
    trace_provider.force_flush()

The pin preserves the SDK modules, not retired models or service endpoints. Migrate the application's imports, client construction and calls using Google's migration guide, then replace VertexAIInstrumentor with GoogleGenAIInstrumentor. Do not enable both instrumentors for the same SDK call.

Troubleshooting

  • ModuleNotFoundError: vertexai.generative_models: migrate to the recommended Google Gen AI route, or install the legacy version shown above. Installing vertexai separately is not the migration.
  • No generation spans after switching to google-genai: replace VertexAIInstrumentor with GoogleGenAIInstrumentor; they target different SDKs.
  • Authentication, model-not-found or location errors: check Application Default Credentials, Vertex AI permissions, and the model's availability in your project and location. Changing the tracing package does not restore retired models.

Metadata

Release files for traceAI-vertexai 0.1.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for traceAI-vertexai 0.1.12
File Size Uploaded Provenance Actions
traceai_vertexai-0.1.12.tar.gz 14.2 kB With provenance Details for traceai_vertexai-0.1.12.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for traceAI-vertexai 0.1.12
File Interpreter ABI Platform Actions
traceai_vertexai-0.1.12-py3-none-any.whl Python 3 none any Details for traceai_vertexai-0.1.12-py3-none-any.whl

Total release size: 29.2 kB

Release files / traceai_vertexai-0.1.12.tar.gz

Download URL traceai_vertexai-0.1.12.tar.gz
Size 14.2 kB
Tags Source
SHA-256 checksum
How to use checksums
fa852859bd52ada5fdb07705b4c8ffc7bae35d850e816bcee0ce2ff91618baa6
BLAKE2b-256 checksum
How to use checksums
6a601bf6b7f8200e0077f38b3c96b7046bd02cd139f67bd84ae0fba92e430607
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / traceai_vertexai-0.1.12-py3-none-any.whl

Download URL traceai_vertexai-0.1.12-py3-none-any.whl
Size 15.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
64099a39dcc04ac70e4d5accc6cd7e1777c3164603de8c804bdf0abc91cafcff
BLAKE2b-256 checksum
How to use checksums
07261c7da9604a2cc0596c9f6c0ba2f340fec7647b837661fa2b13237ebf6acb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for traceAI-vertexai 0.1.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for traceai_vertexai-0.1.12.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page