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

Puedes usar la API del agente de ingeniería de datos, a la que se accede a través de geminidataanalytics.googleapis.com, para compilar, modificar y administrar flujos 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 flujos de datos según tus necesidades de ingeniería de datos.

Para obtener más información sobre el agente de ingeniería de datos, consulta Usa el agente de ingeniería de datos 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 requeridas.

Instala bibliotecas cliente

Instala las siguientes bibliotecas cliente:

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

Extensiones de A2A compatibles

El agente de Ingeniería de datos admite las siguientes extensiones de A2A, algunas de las cuales son obligatorias cuando se interactúa con el agente de Ingeniería de datos.

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

Esta extensión es necesaria para que las conversaciones de varios turnos continúen 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 Es el nivel del mensaje para el control de visibilidad del cliente sobre las actualizaciones de mensajes.

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

Cuando se devuelve DEADLINE_EXCEEDED, el cliente reanuda la tarea desde donde la dejó con el token de conversación que se devolvió en la respuesta en los metadatos.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Instruction Opcional Instrucción del agente definida por el usuario.

El agente que admite esta extensión acepta una lista de instrucciones del agente como contexto adicional con la clave agentInstructions. La instrucción del agente se define según el siguiente esquema:
  • Name: Nombre de la instrucción. Por lo general, es el nombre del archivo.
  • Definition: Definición de la instrucción
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1

Activa la extensión de A2A

Para activar la extensión de 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 del agente de ingeniería de datos.

En el siguiente ejemplo, se muestra una solicitud HTTP para activar la extensión de 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/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/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 del agente.
Enviar mensaje de transmisión POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream Es 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 Es 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.