{"id":7472,"library":"openinference-instrumentation-google-adk","title":"OpenInference Google ADK Instrumentation","description":"This library provides OpenTelemetry instrumentation for Google ADK (Agent Development Kit). It automatically patches Google ADK's runner, agent, LLM, and tool layers to generate spans that adhere to the OpenTelemetry GenAI semantic conventions, enabling detailed observability for Google ADK applications and LLM interactions. It is part of the broader OpenInference project by Arize-AI, which sees frequent updates and new instrumentation releases across various AI/ML frameworks. The current version is 0.1.10. [1, 2, 8, 10, 15]","status":"active","version":"0.1.10","language":"en","source_language":"en","source_url":"https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-google-adk","tags":["observability","opentelemetry","tracing","llm","google","adk","arize","ai","agent-development-kit"],"install":[{"cmd":"pip install openinference-instrumentation-google-adk google-adk opentelemetry-sdk opentelemetry-exporter-otlp","lang":"bash","label":"Recommended Installation"}],"dependencies":[{"reason":"Required for the instrumentation to function, as it instruments components of the Google Agent Development Kit.","package":"google-adk","optional":false},{"reason":"Core OpenInference utilities and base classes.","package":"openinference-instrumentation","optional":false},{"reason":"Defines the semantic conventions for OpenInference traces.","package":"openinference-semantic-conventions","optional":false},{"reason":"OpenTelemetry API for Python.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry base instrumentation classes.","package":"opentelemetry-instrumentation","optional":false},{"reason":"OpenTelemetry SDK for Python, essential for configuring TracerProviders and SpanProcessors.","package":"opentelemetry-sdk","optional":false},{"reason":"Required to export OpenTelemetry traces to a collector.","package":"opentelemetry-exporter-otlp","optional":false},{"reason":"OpenTelemetry semantic conventions.","package":"opentelemetry-semantic-conventions","optional":false},{"reason":"Provides backports of features from future Python versions for type hints.","package":"typing-extensions","optional":false},{"reason":"A utility library for writing robust decorators and object proxies.","package":"wrapt","optional":false}],"imports":[{"symbol":"GoogleADKInstrumentor","correct":"from openinference.instrumentation.google_adk import GoogleADKInstrumentor"}],"quickstart":{"code":"import os\nimport asyncio\nfrom google.adk.agents import Agent\nfrom google.adk.runners import InMemoryRunner\nfrom google.genai import types\n\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\n\nfrom openinference.instrumentation.google_adk import GoogleADKInstrumentor\n\n# Set your Google API Key (replace with your actual key or use env var)\nos.environ[\"GOOGLE_API_KEY\"] = os.environ.get(\"GOOGLE_API_KEY\", \"YOUR_GEMINI_API_KEY_HERE\")\n\n# 1. Configure OpenTelemetry Tracer Provider\n# For simplicity, using ConsoleSpanExporter here. In a real app, use OTLPSpanExporter\n# to send traces to an observability backend like Arize Phoenix, SigNoz, or Langfuse.\nresource = Resource.create({\"service.name\": \"my-adk-agent\"})\ntracer_provider = TracerProvider(resource=resource)\n\n# To export to console (for quick verification):\ntracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\n\n# To export to an OTLP endpoint (e.g., a collector, Phoenix, SigNoz, Langfuse):\n# endpoint = os.environ.get(\"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT\", \"http://localhost:4317\")\n# tracer_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter(endpoint)))\n\ntrace.set_tracer_provider(tracer_provider)\n\n# 2. Instrument Google ADK\nGoogleADKInstrumentor().instrument(tracer_provider=tracer_provider)\n\n# 3. Define a sample Google ADK Agent\ndef get_current_time(city: str) -> dict:\n    \"\"\"Returns the current time for a specified city.\"\"\"\n    # This is a dummy tool, replace with actual logic\n    return {\"status\": \"success\", \"time\": f\"The current time in {city} is 12:00 PM.\"}\n\nagent = Agent(\n    name=\"TimeAgent\",\n    model=\"gemini-pro\", # or \"gemini-2.0-flash-exp\" as per docs\n    description=\"Agent to provide current time in a city.\",\n    instruction=\"You must use the get_current_time tool to find the answer.\",\n    tools=[get_current_time]\n)\n\nasync def main():\n    runner = InMemoryRunner(agent=agent)\n    print(\"Agent started. Ask a question about time.\")\n    user_prompt = \"What time is it in London?\"\n    print(f\"User: {user_prompt}\")\n    response = await runner.run(types.Message(text=user_prompt))\n    print(f\"Agent: {response.text}\")\n\n    user_prompt_2 = \"What about New York?\"\n    print(f\"User: {user_prompt_2}\")\n    response_2 = await runner.run(types.Message(text=user_prompt_2))\n    print(f\"Agent: {response_2.text}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to set up OpenTelemetry tracing for a Google ADK agent using `openinference-instrumentation-google-adk`. It configures a `TracerProvider` (showing both console and OTLP export options), initializes the `GoogleADKInstrumentor`, and then runs a basic ADK agent that uses a tool. Ensure `GOOGLE_API_KEY` is set as an environment variable or directly in the code for Gemini access. [3, 6, 11, 12, 16, 17]"},"warnings":[{"fix":"Stay updated with Google ADK and OpenInference releases. Consult the respective project documentation for any breaking changes related to Pre-GA features.","message":"Google ADK itself may use 'Pre-GA' features. The instrumentation's behavior might be subject to change or have limited support when interacting with these features. Always refer to Google's official ADK documentation for stability status. [5]","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure instrumentation setup (e.g., `GoogleADKInstrumentor().instrument(...)`) is inside the agent module. If conflicts arise, pass `set_global_tracer_provider=False` to your OpenTelemetry provider registration function.","message":"When deploying Google ADK agents to Vertex AI Agent Engine, the instrumentation must be configured within the remote agent module, not in the main application code. Additionally, it might be necessary to set `set_global_tracer_provider=False` when registering the tracer to avoid conflicts with the Agent Engine's own global provider. [11, 17]","severity":"gotcha","affected_versions":"All versions when deploying to Vertex AI Agent Engine"},{"fix":"Set `GOOGLE_API_KEY` in your environment (e.g., `export GOOGLE_API_KEY=\"your_key_here\"`) or pass it directly in your application's configuration where `google-adk` is initialized.","message":"The instrumentation relies on the `GOOGLE_API_KEY` environment variable being correctly set for authentication with Gemini models via Google ADK. Failure to set this will prevent the underlying ADK agent from functioning and thus no traces will be generated. [3, 6, 11, 16, 17]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that `GOOGLE_API_KEY` is set correctly. Ensure you have called `GoogleADKInstrumentor().instrument(tracer_provider=tracer_provider)` and that `tracer_provider` is configured with an active `SpanProcessor` (e.g., `OTLPSpanExporter`) and `trace.set_tracer_provider(tracer_provider)` has been called. Also, confirm your OTLP endpoint is reachable and correct.","cause":"This usually indicates an issue with the OpenTelemetry setup or the Google ADK configuration. Common causes include a missing `GOOGLE_API_KEY`, the `tracer_provider` not being correctly configured or passed to the instrumentor, or the spans not being exported due to an incorrectly configured OTLP exporter endpoint.","error":"No traces appearing in my observability backend/console."},{"fix":"Install the `google-adk` package: `pip install google-adk`.","cause":"The `openinference-instrumentation-google-adk` package instruments the `google-adk` library. While `google-adk` is listed as an optional dependency in some metadata, it is effectively required for the instrumentation to be useful. This error means `google-adk` itself is not installed.","error":"ModuleNotFoundError: No module named 'google.adk'"},{"fix":"Ensure `trace.set_tracer_provider()` is called only once, typically at the application's entry point. If using an external framework that also sets a global tracer, you might need to avoid setting it globally or configure instrumentation at a lower level with a local `tracer_provider` as shown in some deployment examples (e.g., for Agent Engine [17]).","cause":"This error occurs if `opentelemetry.trace.set_tracer_provider()` is called more than once in the application lifecycle. This can happen in complex applications or test environments where instrumentation is repeatedly initialized.","error":"RuntimeError: Cannot set tracer provider multiple times."}]}