API Data Engineering Agent: crie pipelines de dados com um agente

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção "Termos Gerais de Serviço" dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: para enviar feedback sobre esse recurso, envie um e-mail para [e-mail].

É possível usar a API Data Engineering Agent, acessada por geminidataanalytics.googleapis.com, para criar, modificar e gerenciar pipelines de dados para carregar e processar dados no BigQuery. A API usa o protocolo A2A, que permite usar comandos de linguagem natural para gerar e editar pipelines de dados de acordo com suas necessidades de engenharia de dados.

Para mais informações sobre o agente de engenharia de dados, consulte Usar o agente de engenharia de dados para criar e modificar pipelines de dados.

Saiba como e quando o Gemini para Google Cloud usa seus dados.

Como uma tecnologia em estágio inicial, os produtos do Gemini para Google Cloud podem gerar uma saída plausível, mas que é factualmente incorreta. Recomendamos que você valide todas as saídas dos produtos do Gemini para Google Cloud antes de usá-las. Para mais informações, consulte Gemini para Google Cloud e IA responsável.

Observação: as ofertas de pré-lançamento pré-GA (1) são destinadas ao uso apenas em ambientes de teste e não devem ser usadas em um ambiente de produção ou para processar dados pessoais ou outros dados sujeitos a requisitos de conformidade legal ou regulamentar e (2) estão sujeitas aos Termos das Ofertas Pré-GA dos Termos de Serviço Específicos e ao Aditivo de consentimento do Gemini para o Google Cloud Programa Trusted Tester.

Antes de começar

Antes de usar a API Data Engineering Agent, siga as etapas nestas seções.

Ativar APIs

Verifique se você ativou as APIs e tem as permissões necessárias. Para mais informações, consulte Ativar as APIs necessárias.

Instalar bibliotecas de cliente

Instale as seguintes bibliotecas de cliente:

• SDK do Python
• SDK JavaScript/TypeScript
• SDK do Java
• Go SDK
• SDK do.NET

Para mais informações, consulte Protocolo Agent2Agent (A2A).

Extensões A2A compatíveis

O agente de engenharia de dados é compatível com as seguintes extensões A2A, algumas das quais são necessárias ao interagir com ele.

Nome da extensão	Requisito	Descrição	URI
GcpResource	Obrigatório	O ID do recurso Google Cloud em que o agente opera. Isso é obrigatório para cada solicitação.	https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken	Opcional	Uma extensão para o histórico de conversas multiturno como um token de conversa opaco. Essa extensão é necessária para que as conversas multiturno continuem de um estado anterior. Para continuar, copie o valor do token de conversa no campo de metadados da resposta anterior do agente e inclua-o no campo de metadados da próxima solicitação ao agente.	https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel	Opcional	O nível de mensagem para controle de visibilidade do cliente sobre atualizações de mensagens. O agente que oferece suporte a essa extensão anexa o messageLevel a cada message para controle de visibilidade do cliente.	https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason	Opcional	Uma extensão que indica o motivo da interrupção do agente. Quando DEADLINE_EXCEEDED é retornado, o cliente retoma a tarefa de onde parou com o token de conversa retornado na resposta nos metadados.	https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1

Ativar a extensão A2A

Para ativar a extensão A2A, o cliente precisa incluir o cabeçalho A2A-Extensions na solicitação HTTP ao agente. O valor é uma lista separada por vírgulas de URIs de extensão para ativação.

A extensão GcpResource precisa estar ativada para interagir com a API A2A do agente de engenharia de dados.

O exemplo a seguir mostra uma solicitação HTTP para ativar a extensão 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"
}

A resposta pode ser semelhante a esta.

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"
    }
  }
}

Principais operações da API

A API fornece os seguintes endpoints principais para usar o agente de engenharia de dados:

Operação	Método HTTP	Endpoint	Descrição
Acessar card do agente	GET	/v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card	Recupera as informações do card do agente.
Enviar mensagem de streaming	POST	/v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream	Um método de streaming para enviar um comando ao agente e receber respostas de streaming. A seguinte permissão é necessária: geminidataanalytics.locations.useDataEngineeringAgent.
Enviar mensagem	POST	/v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:send	Um método unário para enviar um comando ao agente e receber uma resposta síncrona. Isso pode ser útil para validação rápida ou perguntas de uma única rodada. A seguinte permissão é necessária: geminidataanalytics.locations.useDataEngineeringAgent.

Outros recursos

Para descrições detalhadas de métodos, endpoints e definições de tipo para estruturas de solicitação e resposta, consulte a referência da API REST do agente de engenharia de dados.