Instrumenta aplicaciones del ADK con OpenTelemetry

En este documento, se describe cómo instrumentar un agente de IA creado con el framework del Kit de desarrollo de agentes (ADK). Esta instrumentación, que aprovecha OpenTelemetry, te permite recopilar instrucciones del usuario, respuestas del agente y opciones del agente.

El propio framework del ADK está instrumentado con OpenTelemetry, que captura la telemetría de los pasos clave en la ejecución de tu agente. Esto proporciona una valiosa observabilidad de la aplicación lista para usar. Sin embargo, es posible que esta observabilidad no sea suficiente para el caso de uso de tu aplicación. Puedes agregar bibliotecas de instrumentación adicionales con OpenTelemetry para capturar telemetría de otras partes de tu app o tu propia instrumentación personalizada para capturar datos específicos de la aplicación y obtener una observabilidad más detallada.

Por ejemplo, en tu aplicación, podrías escribir código de instrumentación para hacer lo siguiente:

  • Realizar un seguimiento del consumo de recursos de las herramientas invocadas por el agente
  • Realiza un seguimiento de los errores de validación específicos de la aplicación, los incumplimientos de reglas comerciales o los mecanismos personalizados de recuperación de errores.
  • Realiza un seguimiento de las puntuaciones de calidad de las respuestas de los agentes según tus criterios específicos del dominio.

Instrumenta tu aplicación de IA generativa para recopilar telemetría

Para instrumentar tu agente de IA y recopilar datos de registros, métricas y seguimiento, haz lo siguiente:

  1. Instala los paquetes de OpenTelemetry
  2. Configura OpenTelemetry para recopilar y enviar telemetría
  3. Escribe un punto de entrada personalizado para insertar OpenTelemetry configurado

En el resto de esta sección, se describen los pasos anteriores.

Instala los paquetes de OpenTelemetry

Agrega los siguientes paquetes de instrumentación y exportación de OpenTelemetry:

pip install 'opentelemetry-instrumentation-google-genai' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Los datos de registros y métricas se envían a tu proyecto Google Cloud a través de la API de Cloud Logging o la API de Cloud Monitoring. Las bibliotecas opentelemetry-exporter-gcp-logging y opentelemetry-exporter-gcp-monitoring invocan extremos en esas APIs.

Los datos de seguimiento se envían a Google Cloud con la API de Telemetry (OTLP), que admite el formato de OTLP. Los datos que se reciben a través de este extremo también se almacenan en formato OTLP. La biblioteca opentelemetry-exporter-otlp-proto-grpc invoca el extremo de API de Telemetry (OTLP).

Configura OpenTelemetry para recopilar y enviar telemetría

En el código de inicialización de tu agente del ADK, agrega código para configurar OpenTelemetry de modo que capture y envíe telemetría a tu proyecto de Google Cloud :

Para ver la muestra completa, haz clic en Más y, luego, selecciona Ver en GitHub.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Escribe un punto de entrada personalizado para usar OpenTelemetry configurado

Para usar OpenTelemetry en la instrumentación, crea un punto de entrada personalizado para tu aplicación del ADK. El punto de entrada personalizado debe configurar OpenTelemetry antes de iniciar el agente del ADK.

En la aplicación de ejemplo, el método main actúa como un punto de entrada personalizado que inicializa OpenTelemetry y, luego, lanza el servidor FastAPI, que te permite interactuar con el agente.

Para ver la muestra completa, haz clic en Más y, luego, selecciona Ver en GitHub.

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

Descarga y ejecuta la aplicación de muestra

En este código de muestra, se implementa un agente de IA generativa creado con el ADK. El agente está instrumentado con OpenTelemetry y configurado para enviar métricas, registros y seguimientos a tu proyecto Google Cloud . La telemetría que se envía a tu proyecto incluye instrucciones y respuestas de IA generativa.

Arquetipo de agente de ADK

El agente de IA generativa se define como un experto en SQL que tiene acceso completo a una base de datos SQLite efímera. El agente se compila con el Agent Development Kit y accede a una base de datos con el SQLDatabaseToolkit. Inicialmente, la base de datos está vacía.

Antes de comenzar

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

  3. Para obtener los permisos que necesitas para que las aplicaciones de ejemplo escriban datos de registros, métricas y seguimiento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

    4. Inicia la aplicación

    Para iniciar la aplicación de ejemplo, haz lo siguiente:

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    2. Clona el repositorio:

      git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git

    3. Ve al directorio de muestra:

      cd opentelemetry-operations-python/samples/adk-sql-agent

    4. Crea un entorno virtual y ejecuta la muestra:

      python -m venv venv/
source venv/bin/activate
pip install -r requirements.txt
env $(cat opentelemetry.env | xargs) python main.py

      La aplicación muestra un mensaje similar al siguiente:

      Appplication startup complete
Uvicorn running on http://0.0.0.0:8080

    5. Para interactuar con el agente, abre un navegador en la dirección que se indica en el paso anterior.

    6. Expande Selecciona un agente y selecciona sql_agent de la lista de agentes.

      7. Interactúa con el agente

      Para interactuar con el agente, hazle una pregunta o dale un comando. Por ejemplo, podrías hacer la siguiente pregunta:

      What can you do for me ?

      Del mismo modo, dado que sql_agent tiene la personalidad de un experto en SQL, puedes pedirle que cree tablas para tus aplicaciones y escriba consultas para operar en las tablas creadas. El agente solo puede crear una base de datos efímera respaldada por un archivo .db que se crea en la máquina que ejecuta la aplicación.

      A continuación, se ilustra una interacción de ejemplo entre sql_agent y el usuario:

      Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.

      Es la visualización de la interacción con sql_agent.

      Las acciones que realizan los agentes de IA generativa no son determinísticas, por lo que es posible que veas una respuesta diferente para la misma instrucción.

      Salir de la aplicación

      Para salir de la aplicación, ingresa Ctrl-C en el shell que se usó para iniciarla.

      Visualiza los registros, las métricas y los seguimientos

      En esta sección, se describe cómo puedes ver los eventos de IA generativa.

      Antes de comenzar

      Para obtener los permisos que necesitas para ver tus datos de registros, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

      Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

      También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

      Ver telemetría

      Para ver los eventos de IA generativa creados por la aplicación, usa la página Explorador de registros:

      1. En la consola de Google Cloud , ve a la página Explorador de seguimiento:

        Ve al Explorador de seguimiento

        También puedes usar la barra de búsqueda para encontrar esta página.

      2. En la barra de herramientas, selecciona Agregar filtro, luego Nombre del tramo y, por último, call_llm.

        En la siguiente ilustración, se muestra la página del Explorador de seguimiento después de filtrar los datos:

        Visualización de intervalos de seguimiento.

        Si nunca usaste Cloud Trace, Google Cloud Observability debe crear una base de datos para almacenar tus datos de seguimiento. La creación de la base de datos puede tardar unos minutos y, durante ese período, no habrá datos de seguimiento disponibles para ver.

      3. Para explorar tus datos de registros y de intervalos, selecciona un intervalo en la tabla Intervalos.

        Se abrirá la página Detalles. En esta página, se muestran el registro asociado y sus intervalos. En la tabla de la página, se muestra información detallada sobre el intervalo que seleccionaste. Esta información incluye lo siguiente:

        • En la pestaña GenAI, se muestran los eventos de los agentes de IA generativa. Para obtener más información sobre estos eventos, consulta Cómo ver eventos de IA generativa.

          En la siguiente captura de pantalla, se ilustra un registro, en el que un intervalo tiene el nombre call_llm. Ese tramo invoca el LLM (modelo de lenguaje grande) que potencia este agente. En este ejemplo, es Gemini. El intervalo de Gemini incluye eventos de IA generativa:

          Se muestran eventos de IA generativa.

        • En la pestaña Registros y eventos, se enumeran las entradas de registro y los eventos asociados con el intervalo. Si deseas ver los datos de registro en el Explorador de registros, selecciona Ver registros en la barra de herramientas de esta pestaña.

          Los datos de registro incluyen la respuesta de sql_agent. Por ejemplo, para la ejecución de muestra, la carga útil de JSON incluye el siguiente contenido:

          {
  "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
  "jsonPayload": {
    "content": {
      "role": "model",
      "parts": [
        {
          "executable_code": null,
          "inline_data": null,
          "thought": null,
          "video_metadata": null,
          "code_execution_result": null,
          "function_response": null,
          "thought_signature": null,
          "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
          "file_data": null,
          "function_call": null
        }
      ]
    }
  },
  ...
}

      La muestra está instrumentada para enviar datos de métricas a tu proyecto de Google Cloud , pero no genera ninguna métrica.