Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Organiza agentes de datos con A2A

La API de Conversational Analytics en Google Cloud implementa el protocolo Agent-to-Agent (A2A) abierto, que permite que los agentes en flujos de trabajo multiagente descubran capacidades, deleguen consultas analíticas y transmitan respuestas estructuradas, como consultas en SQL ejecutables y visualizaciones de gráficos.

Puedes consultar los agentes de datos integrados en la API de Conversational Analytics para BigQuery y Looker pasando el contexto del conjunto de datos en tu solicitud a la API, o bien puedes consultar los agentes de datos personalizados que se configuran con la lógica empresarial de tu organización.

Para compilar y consultar agentes de datos directamente, consulta Cómo compilar un agente de datos con el SDK de Python o Cómo compilar un agente de datos con HTTP.

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

Cómo funciona la organización de agentes de datos

Cuando integras agentes de datos de la API de Conversational Analytics en una aplicación o un sistema multiagente, el flujo de trabajo de organización sigue estas operaciones:

El agente orquestador descubre las capacidades y habilidades de un agente de datos inspeccionando su tarjeta de agente antes de delegar consultas analíticas.
El agente orquestador envía un mensaje para consultar un agente de datos integrado (agents/bigquery-ca o agents/looker-ca) especificando fuentes de datos en la solicitud, o bien un agente de datos personalizado (dataAgents/DATA_AGENT_ID) que se configura con lógica empresarial del dominio.
El agente de datos procesa la solicitud, ejecuta las consultas necesarias y devuelve los resultados, ya sea como una respuesta completa o transmitiendo el progreso del razonamiento y los artefactos estructurados (como SQL ejecutable y especificaciones de gráficos de Vega-Lite).

Antes de comenzar

Antes de comenzar, completa los siguientes requisitos previos:

Habilita la API de Conversational Analytics, la API de BigQuery y la API de Looker en tu proyecto Google Cloud .
Verifica que tengas los roles y permisos de IAM necesarios.
Autentícate en la API de Conversational Analytics y, luego, instala la biblioteca cliente u obtén un token de autorización.

Roles obligatorios

Para obtener los permisos que necesitas para descubrir y consultar agentes de datos a través de A2A, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Usuario del agente de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentUser)
Para consultas sin estado: Usuario sin estado del agente de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentStatelessUser)

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.

Para consultar las fuentes de datos subyacentes, también debes tener permisos de lectura en tus conjuntos de datos de BigQuery (como roles/bigquery.dataViewer) o en los Explorar de Looker de destino.

Descubre las capacidades de los agentes

Antes de delegar consultas a un agente de datos, un agente de orquestación o una aplicación cliente pueden inspeccionar la tarjeta del agente para ver sus capacidades y configuración, como su descripción, las habilidades disponibles y las extensiones compatibles. Puedes recuperar tarjetas de agentes con el método getCard para los agentes de datos integrados (agents/bigquery-ca y agents/looker-ca) y los agentes de datos personalizados (dataAgents/DATA_AGENT_ID).

Cómo recuperar una tarjeta de agente

En los siguientes ejemplos de código, se muestra cómo recuperar una tarjeta de agente. En estos ejemplos, se usa el agente de datos integrado de BigQuery (agents/bigquery-ca) como ejemplo, pero puedes recuperar la tarjeta del agente integrado de Looker (agents/looker-ca) o de un agente de datos personalizado (dataAgents/DATA_AGENT_ID) si cambias el nombre del recurso del agente en tu solicitud:

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.GetAgentCardRequest(tenant=agent_name)
card = client.get_agent_card(request=request)

print(card)

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la ubicación del recurso del agente (como us, us-east4, eu o global).

HTTP

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/card"

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la ubicación del recurso del agente (como us, us-east4, eu o global).

Comprende la estructura de la tarjeta del agente

Una solicitud correcta devuelve un objeto de tarjeta de agente que contiene metadatos, habilidades compatibles y extensiones:

{
  "name": "BigQuery Conversational Analytics Agent",
  "description": "This agent can answer questions about your data using BigQuery.",
  "protocolVersion": "1.0",
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Provides data analysis assistance",
      "examples": [
        "What is the total sales for the last 3 months?"
      ],
      "inputModes": [
        "text/plain"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    }
  ],
  "capabilities": {
    "streaming": true,
    "extensions": [
      {
        "uri": "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1",
        "description": "Google Data Analytics BigQuery Context extension"
      }
    ]
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ]
}

La tarjeta del agente incluye los siguientes campos:

name: El nombre visible del agente de datos
description: Es un resumen de las capacidades analíticas del agente de datos.
protocolVersion: Es la versión del protocolo A2A que admite el extremo (por ejemplo, 1.0).
skills: Las tareas que puede realizar el agente de datos, incluidas las instrucciones de muestra (examples) y los formatos de datos admitidos (inputModes y outputModes, como text/plain o application/json)
capabilities.streaming: Es un valor booleano que indica si el agente de datos admite la transmisión en tiempo real a través del método stream.
capabilities.extensions: Son las extensiones de A2A que admite el agente de datos, como bigquery_context/v1, stateless/v1 y kms/v1.
defaultInputModes y defaultOutputModes: Son los formatos de datos predeterminados (como text/plain o application/json) para las cargas útiles de solicitudes y respuestas.

Envía un mensaje a un agente de datos

Para enviar un mensaje a un agente de datos, usa el método send. El agente de datos procesa la solicitud, genera y ejecuta las consultas en SQL necesarias en tus datos, y devuelve la respuesta en lenguaje natural junto con los artefactos de datos generados.

Envía un mensaje

Cuando envíes un mensaje, especifica el agente de datos de destino en la ruta de acceso del recurso:

Para los agentes de datos integrados (agents/bigquery-ca o agents/looker-ca), pasa referencias de la tabla de destino o de la exploración en el campo metadata con la extensión bigquery_context/v1 o looker_context/v1.
En el caso de los agentes de datos personalizados (dataAgents/DATA_AGENT_ID), omite el campo metadata, ya que el contexto, los esquemas y las instrucciones se configuran directamente en el recurso del agente.

Para procesar consultas sin almacenar el historial de conversaciones en Google Cloud, incluye la extensión stateless/v1 en tu solicitud. Para encriptar los metadatos y los datos de conversaciones almacenados con una clave de encriptación administrada por el cliente, pasa la extensión kms/v1 con el nombre de tu clave de Cloud KMS. Para obtener más información, consulta Claves de encriptación administradas por el cliente (CMEK).

En los siguientes ejemplos de código, se muestra cómo enviar un mensaje al agente de datos integrado de BigQuery:

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.SendMessageRequest(
    tenant=agent_name,
    message=geminidataanalytics_v1.Message(
        role="ROLE_USER",
        # Optional: Pass context_id to continue an existing conversation
        # context_id="projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID",
        parts=[
            geminidataanalytics_v1.Part(
                text="What are the top 5 countries where our users are located?"
            )
        ],
    ),
    configuration=geminidataanalytics_v1.SendMessageConfiguration(
        return_immediately=False
    ),
    metadata={
        "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
            "datasource_references": {
                "bq": {
                    "tableReferences": [
                        {
                            "projectId": "DATASET_PROJECT_ID",
                            "datasetId": "DATASET_ID",
                            "tableId": "TABLE_ID",
                        }
                    ]
                }
            }
        },
        # Optional: Process queries without storing conversation history in Google Cloud
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/stateless/v1": {},
        # Optional: Encrypt conversation history and metadata with a customer-managed encryption key (CMEK)
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/kms/v1": {
        #     "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
        # },
    },
)

response = client.send_message(request=request)

print(response)

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la ubicación del recurso del agente (como us, us-east4, eu o global).
CONVERSATION_ID: (Opcional) Es el ID de una sesión de conversación existente para continuar.
What are the top 5 countries where our users are located?: Es la pregunta en lenguaje natural que se le hará al agente de datos.
DATASET_PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el conjunto de datos de BigQuery (por ejemplo, bigquery-public-data).
DATASET_ID: Es el ID del conjunto de datos de BigQuery (por ejemplo, thelook_ecommerce).
TABLE_ID: Es el ID de la tabla de BigQuery (por ejemplo, users).
KEY_RING: (Opcional) Es el nombre del llavero de claves de Cloud KMS cuando se usa la CMEK.
KEY_NAME: (Opcional) Es el nombre de la clave criptográfica de Cloud KMS cuando se usa la CMEK.

HTTP

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "A2A-Extensions: https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "What are the top 5 countries where our users are located?"
        }
      ]
    },
    "configuration": {
      "return_immediately": false
    },
    "metadata": {
      "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
        "datasource_references": {
          "bq": {
            "tableReferences": [
              {
                "projectId": "DATASET_PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID"
              }
            ]
          }
        }
      }
    }
  }' \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/message:send"

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la ubicación del recurso del agente (como us, us-east4, eu o global).
What are the top 5 countries where our users are located?: Es la pregunta en lenguaje natural que se le hará al agente de datos.
DATASET_PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el conjunto de datos de BigQuery (por ejemplo, bigquery-public-data).
DATASET_ID: Es el ID del conjunto de datos de BigQuery (por ejemplo, thelook_ecommerce).
TABLE_ID: Es el ID de la tabla de BigQuery (por ejemplo, users).

Comprende la estructura de la respuesta

Una solicitud correcta devuelve un objeto task que contiene el estado final, el identificador de la conversación y los artefactos generados:

{
  "task": {
    "id": "ab12d1f2-e170-4c4f-aff4-be466c6beaaa",
    "contextId": "projects/my-project/locations/us/conversations/conv-67890",
    "status": {
      "state": "TASK_STATE_COMPLETED"
    },
    "artifacts": [
      {
        "artifactId": "synthetic-8a368e8e-378a-4b80-9f07-0b1a397c221d",
        "name": "Final response",
        "description": "Final response from the agent.",
        "parts": [
          {
            "text": "The top 5 countries where our users are located are China (33,783), the United States (22,701), Brasil (14,620), South Korea (5,302), and France (4,645)."
          }
        ]
      },
      {
        "artifactId": "synthetic-50483808-b231-4b30-a859-2c30d0355a8d",
        "name": "Generated SQL",
        "description": "Generated SQL from the agent.",
        "parts": [
          {
            "text": "SELECT country, COUNT(DISTINCT id) AS user_count FROM `bigquery-public-data.thelook_ecommerce.users` GROUP BY country ORDER BY user_count DESC LIMIT 5",
            "mediaType": "text/x-sql"
          }
        ]
      }
    ]
  }
}

La respuesta incluye los siguientes campos clave:

task.id: Es el identificador único de la tarea de ejecución.
task.contextId: Es la ruta de acceso del recurso de la conversación, que pasas en el campo message.contextId de las solicitudes posteriores para continuar la sesión.
task.status.state: Es el estado de ejecución de la tarea (por ejemplo, TASK_STATE_COMPLETED).
task.artifacts[]: Son los recursos estructurados que genera el agente de datos, como la respuesta en lenguaje natural (Final response), la consulta en SQL ejecutable (Generated SQL) y las filas de resultados tabulares (Data result).

Transmite respuestas desde un agente de datos

Para recibir actualizaciones en tiempo real a medida que el agente de datos razona a través de una consulta, usa el método stream. La respuesta transmite actualizaciones de estado (status_update) con reflexiones intermedias y artefactos incrementales (artifact_update), como consultas en SQL generadas y especificaciones de gráficos de Vega-Lite.

Las solicitudes de transmisión también admiten conversaciones continuas (context_id), procesamiento sin estado (stateless/v1) y claves de encriptación administradas por el cliente (kms/v1).

Envía un mensaje de transmisión

En los siguientes ejemplos de código, se muestra cómo transmitir eventos desde el agente de datos integrado de BigQuery. Para transmitir desde un agente de datos personalizado (dataAgents/DATA_AGENT_ID), establece como objetivo la ruta del recurso del agente personalizado y omite el campo metadata:

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.SendMessageRequest(
    tenant=agent_name,
    message=geminidataanalytics_v1.Message(
        role="ROLE_USER",
        parts=[
            geminidataanalytics_v1.Part(
                text="What are the top 5 countries where our users are located? Please show a pie chart."
            )
        ],
    ),
    metadata={
        "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
            "datasource_references": {
                "bq": {
                    "tableReferences": [
                        {
                            "projectId": "DATASET_PROJECT_ID",
                            "datasetId": "DATASET_ID",
                            "tableId": "TABLE_ID",
                        }
                    ]
                }
            }
        },
        # Optional: Process queries without storing conversation history in Google Cloud
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/stateless/v1": {},
        # Optional: Encrypt conversation history and metadata with a customer-managed encryption key (CMEK)
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/kms/v1": {
        #     "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
        # },
    },
)

# Stream response events
stream = client.send_streaming_message(request=request)

for chunk in stream:
  print(chunk)

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la ubicación del recurso del agente (como us, us-east4, eu o global).
What are the top 5 countries where our users are located? Please show a pie chart.: Es la pregunta en lenguaje natural que se le hará al agente de datos.
DATASET_PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el conjunto de datos de BigQuery (por ejemplo, bigquery-public-data).
DATASET_ID: Es el ID del conjunto de datos de BigQuery (por ejemplo, thelook_ecommerce).
TABLE_ID: Es el ID de la tabla de BigQuery (por ejemplo, users).
KEY_RING: (Opcional) Es el nombre del llavero de claves de Cloud KMS cuando se usa la CMEK.
KEY_NAME: (Opcional) Es el nombre de la clave criptográfica de Cloud KMS cuando se usa la CMEK.

HTTP

curl -X POST \
  -N \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: text/event-stream, application/json" \
  -H "A2A-Extensions: https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "What are the top 5 countries where our users are located? Please show a pie chart."
        }
      ]
    },
    "metadata": {
      "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
        "datasource_references": {
          "bq": {
            "tableReferences": [
              {
                "projectId": "DATASET_PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID"
              }
            ]
          }
        }
      }
    }
  }' \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/message:stream"

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la ubicación del recurso del agente (como us, us-east4, eu o global).
What are the top 5 countries where our users are located? Please show a pie chart.: Es la pregunta en lenguaje natural que se le hará al agente de datos.
DATASET_PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el conjunto de datos de BigQuery (por ejemplo, bigquery-public-data).
DATASET_ID: Es el ID del conjunto de datos de BigQuery (por ejemplo, thelook_ecommerce).
TABLE_ID: Es el ID de la tabla de BigQuery (por ejemplo, users).

Comprende la estructura de la respuesta de transmisión

Cuando envías una solicitud de transmisión, el servidor devuelve un flujo de objetos de eventos (StreamResponse). Cada evento contiene una actualización de estado o una actualización de artefacto.

Los eventos de actualización de estado entregan notificaciones de progreso intermedio y mensajes de reflexión a medida que el agente de datos razona a través de tu búsqueda:

{
  "statusUpdate": {
    "taskId": "f41cd8e3-e665-460c-aceb-7b337f1848ef",
    "status": {
      "state": "TASK_STATE_WORKING",
      "message": {
        "role": "ROLE_AGENT",
        "parts": [
          {
            "text": "Analyzing context"
          },
          {
            "text": "Retrieved context for 1 table."
          }
        ]
      }
    }
  }
}

Los eventos de actualización de artefactos entregan objetos de salida estructurados, como consultas SQL ejecutables, respuestas en lenguaje natural o especificaciones de gráficos:

{
  "artifactUpdate": {
    "taskId": "f41cd8e3-e665-460c-aceb-7b337f1848ef",
    "artifact": {
      "artifactId": "synthetic-7ca98286-0a15-4ca0-a8bc-f14dc231b3ba",
      "name": "Chart result",
      "description": "Chart visualization generated by the data agent.",
      "parts": [
        {
          "data": {
            "title": "Top 5 Countries by User Population",
            "mark": "arc",
            "encoding": {
              "color": {
                "field": "country",
                "type": "nominal"
              },
              "theta": {
                "field": "user_count",
                "type": "quantitative"
              }
            },
            "data": {
              "values": [
                {
                  "country": "China",
                  "user_count": 33783
                },
                {
                  "country": "United States",
                  "user_count": 22701
                },
                {
                  "country": "Brasil",
                  "user_count": 14620
                },
                {
                  "country": "South Korea",
                  "user_count": 5302
                },
                {
                  "country": "France",
                  "user_count": 4645
                }
              ]
            }
          }
        }
      }
    },
    "lastChunk": true
  }
}

La respuesta de transmisión incluye los siguientes campos clave:

statusUpdate.status.state: Es el estado intermedio o final de la tarea (como TASK_STATE_WORKING o TASK_STATE_COMPLETED).
statusUpdate.status.message.parts[]: Son las descripciones del pensamiento o del progreso que se emiten durante la ejecución.
artifactUpdate.artifact: Es el recurso estructurado que genera el agente de datos, como una especificación de gráfico de Vega-Lite (data) o una consulta en SQL (text).
artifactUpdate.lastChunk: Es una marca booleana que indica si se completó la transmisión del artefacto.

Para renderizar la especificación de Vega o Vega-Lite que se devolvió en Python o en aplicaciones de frontend, consulta Renderiza una respuesta del agente como una visualización.

¿Qué sigue?

Aprende a renderizar respuestas del agente como visualizaciones con Vega-Lite y Altair.
Aprende a guiar el comportamiento de los agentes con contexto creado para configurar reglas comerciales y búsquedas verificadas.
Explora los patrones de integración arquitectónica para sistemas multiagente.
Revisa la referencia de la API de Data Analytics with Gemini en REST.

Organiza agentes de datos con A2A Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Cómo funciona la organización de agentes de datos

Antes de comenzar

Roles obligatorios

Descubre las capacidades de los agentes

Cómo recuperar una tarjeta de agente

Python SDK

HTTP

Comprende la estructura de la tarjeta del agente

Envía un mensaje a un agente de datos

Envía un mensaje

Python SDK

HTTP

Comprende la estructura de la respuesta

Transmite respuestas desde un agente de datos

Envía un mensaje de transmisión

Python SDK

HTTP

Comprende la estructura de la respuesta de transmisión

¿Qué sigue?

Organiza agentes de datos con A2A