데이터 엔지니어링 에이전트 API: 에이전트로 데이터 파이프라인 빌드

geminidataanalytics.googleapis.com을 통해 액세스되는 Data Engineering Agent API를 사용하여 BigQuery에서 데이터를 로드하고 처리하기 위한 데이터 파이프라인을 빌드, 수정, 관리할 수 있습니다. 이 API는 자연어 프롬프트를 사용하여 데이터 엔지니어링 요구사항에 맞게 데이터 파이프라인을 생성하고 수정할 수 있는 A2A 프로토콜을 사용합니다.

Data Engineering Agent에 대한 자세한 내용은 데이터 엔지니어링 에이전트를 사용하여 데이터 파이프라인 빌드 및 수정을 참조하세요.

를 위한 Gemini에서 사용자 데이터를 사용하는 방법과 시점을 알아보세요. Google Cloud

Google Cloud

시작하기 전에

Data Engineering Agent API를 사용하기 전에 이 섹션의 단계를 수행하세요.

API 사용 설정

필수 API를 사용 설정하고 필수 권한이 있는지 확인합니다. 자세한 내용은 필수 API 사용 설정을 참조하세요.

클라이언트 라이브러리 설치

다음 클라이언트 라이브러리를 설치합니다.

자세한 내용은 Agent2Agent (A2A) 프로토콜을 참조하세요.

지원되는 A2A 확장 프로그램

Data Engineering Agent는 다음과 같은 A2A 확장 프로그램을 지원하며, Data Engineering Agent와 상호작용할 때 일부 확장 프로그램이 필요합니다.

확장 프로그램 이름 요구사항 설명 URI
GcpResource 필수 에이전트가 작동하는 리소스의 리소스 ID입니다. Google Cloud 각 요청에 필요합니다. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken 선택사항 불투명 대화 토큰으로 멀티턴 대화 기록을 위한 확장 프로그램입니다.

이 확장 프로그램은 멀티턴 대화에서 이전 상태에서 대화를 계속하는 데 필요합니다. 계속하려면 에이전트의 이전 응답의 메타데이터 필드에서 대화 토큰 값을 복사하여 에이전트에 대한 다음 요청의 메타데이터 필드에 포함합니다.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel 선택사항 메시지 업데이트에 대한 클라이언트 공개 상태 제어를 위한 메시지 수준입니다.

이 확장 프로그램을 지원하는 에이전트는 클라이언트 공개 상태 제어를 위해 각 message에 messageLevel을 연결합니다.		 https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason 선택사항 에이전트가 중지된 이유를 나타내는 확장 프로그램입니다.

DEADLINE_EXCEEDED가 반환되면 클라이언트는 메타데이터의 응답에서 반환된 대화 토큰으로 중단된 지점부터 작업을 재개합니다.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1

A2A 확장 프로그램 활성화

A2A 확장 프로그램을 활성화하려면 클라이언트가 에이전트에 대한 HTTP 요청에 A2A-Extensions 헤더를 포함해야 합니다. 값은 활성화를 위한 확장 프로그램 URI의 쉼표로 구분된 목록입니다.

Data Engineering Agent A2A API와 상호작용하려면 GcpResource 확장 프로그램을 활성화해야 합니다.

다음 예는 A2A 확장 프로그램을 활성화하는 HTTP 요청을 보여줍니다.

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

응답은 다음과 비슷할 수 있습니다.

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

주요 API 작업

이 API는 Data Engineering Agent를 사용하기 위한 다음과 같은 핵심 엔드포인트를 제공합니다.

작업 HTTP 메서드 엔드포인트 설명
에이전트 카드 가져오기 GET /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card 에이전트 카드 정보를 가져옵니다.
스트리밍 메시지 전송 POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream 에이전트에 프롬프트를 전송하고 스트리밍 응답을 수신하는 스트리밍 메서드입니다.

다음 권한이 필요합니다. geminidataanalytics.locations.useDataEngineeringAgent.
메시지 보내기 POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:send 에이전트에 프롬프트를 전송하고 동기 응답을 수신하는 단항 메서드입니다. 빠른 유효성 검사 또는 단일 턴 질문에 유용할 수 있습니다.

다음 권한이 필요합니다. geminidataanalytics.locations.useDataEngineeringAgent.

추가 리소스

요청 및 응답 구조의 메서드, 엔드포인트, 유형 정의에 대한 자세한 설명은 Data Engineering Agent API REST 참조를 확인하세요.