API de Data Engineering Agent: Crea canalizaciones de datos con un agente

Puedes usar la API de Data Engineering Agent, a la que se accede a través de geminidataanalytics.googleapis.com, para compilar, modificar y administrar canalizaciones de datos para cargar y procesar datos en BigQuery. La API usa el protocolo A2A que te permite usar instrucciones en lenguaje natural para generar y editar canalizaciones de datos para tus necesidades de ingeniería de datos.

Para obtener más información sobre Data Engineering Agent, consulta Usa Data Engineering Agent para compilar y modificar canalizaciones de datos.

Descubre cómo y cuándo Gemini para Google Cloud usa tus datos.

Antes de comenzar

Antes de usar la API de Data Engineering Agent, sigue los pasos que se indican en estas secciones.

Habilita las APIs

Asegúrate de haber habilitado las APIs necesarias y de tener los permisos requeridos Para obtener más información, consulta Habilita las APIs necesarias.

Instala bibliotecas cliente

Instala las siguientes bibliotecas cliente:

Para obtener más información, consulta Protocolo Agent2Agent (A2A).

Extensiones A2A compatibles

Data Engineering Agent admite las siguientes extensiones A2A, algunas de las cuales son necesarias cuando se interactúa con Data Engineering Agent.

Nombre de la extensión Requisito Descripción URI
GcpResource Obligatorio El Google Cloud ID de recurso para el recurso en el que opera el agente. Esto es obligatorio para cada solicitud. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken Opcional Una extensión para el historial de conversaciones de varios turnos como un token de conversación opaco.

Esta extensión es necesaria para que las conversaciones de varios turnos continúen la conversación desde un estado anterior. Para continuar, copia el valor del token de conversación en el campo de metadatos de la respuesta anterior del agente y, luego, inclúyelo en el campo de metadatos de la siguiente solicitud al agente.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel Opcional El nivel de mensaje para el control de visibilidad del cliente sobre las actualizaciones de mensajes.

El agente que admite esta extensión adjunta el messageLevel a cada message para el control de visibilidad del cliente.		 https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason Opcional Una extensión que indica el motivo por el que se detuvo el agente.

Cuando se muestra DEADLINE_EXCEEDED, el cliente reanuda la tarea desde donde la dejó con el token de conversación que se muestra en la respuesta en los metadatos.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1

Activa la extensión A2A

Para activar la extensión A2A, tu cliente debe incluir el encabezado A2A-Extensions en la solicitud HTTP al agente. El valor es una lista separada por comas de los URIs de extensión para la activación.

La extensión GcpResource debe activarse para interactuar con la API de A2A de Data Engineering Agent.

En el siguiente ejemplo, se muestra una solicitud HTTP para activar la extensión A2A.

POST /v1/a2a/projects/{project}/locations/{location}/agents/dataengineeringagent/v1/message:stream HTTP/1.1
Host: geminidataanalytics.googleapis.com
Content-Type: application/json
Authorization: Bearer $(gcloud auth print-access-token)
A2A-Extensions: https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/pipelinecontext/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Content-Length: 869

{
  "request": {
    "messageId": "0ad14bfa-8d17-48ce-8669-52a856129a66",
    "role": "ROLE_USER",
    "contextId": "test-context-id",
    "content": [{
      "text": "hi"
    }]
  },
  "metadata": {
    "https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1": "cmVxdWVzdGNvbnZlcnNhdGlvbnRva2Vu",
    "https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1": {
      "gcpResourceId": "projects/{project}/locations/{location}/repositories/{repository}/workspaces/{workspace}"
    },
   "https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1": {
      "agentInstructions": [{
        "definition": "Always use uppercase for SQL keywords.",
        "name": "style_guide.md"
      }]
    }
  },
  "tenant": "projects/{project}/locations/{location}/agents/dataengineeringagent"
}

La respuesta podría ser similar a la siguiente.

HTTP/1.1 200 OK
Content-Type: application/json
A2A-Extensions: https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/pipelinecontext/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Transfer-Encoding: chunked

{
  "statusUpdate": {
    "status": {
      "state": "TASK_STATE_COMPLETED",
      "timestamp": "example-timestamp"
    },
    "final": true,
    "metadata": {
      "https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1": "Y29udmVyc2F0aW9udG9rZW4=",
      "https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1": "FINISHED"
    }
  }
}

Operaciones clave de la API

La API proporciona los siguientes extremos principales para usar Data Engineering Agent:

Operación Método HTTP Extremo Descripción
Obtener tarjeta de agente GET /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card Recupera la información de la tarjeta de agente.
Enviar mensaje de transmisión POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream Un método de transmisión para enviar una instrucción al agente y recibir respuestas de transmisión.

Se requiere el siguiente permiso: geminidataanalytics.locations.useDataEngineeringAgent.
Enviar mensaje POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:send Un método unario para enviar una instrucción al agente y recibir una respuesta síncrona. Esto puede ser útil para la validación rápida o las preguntas de un solo turno.

Se requiere el siguiente permiso: geminidataanalytics.locations.useDataEngineeringAgent.

Recursos adicionales

Para obtener descripciones detalladas de los métodos, los extremos y las definiciones de tipos para las estructuras de solicitud y respuesta, consulta la referencia de la API de REST de Data Engineering Agent.