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

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

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

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

시작하기 전에

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

API 사용 설정

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

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

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

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

지원되는 A2A 확장 프로그램

데이터 엔지니어링 에이전트는 다음 A2A 확장 프로그램을 지원하며, 데이터 엔지니어링 에이전트와 상호작용할 때 일부가 필요합니다.

확장 프로그램 이름 요구사항 설명 URI
GcpResource 필수 에이전트가 Google Cloud 작업하는 리소스의 리소스 ID입니다. 각 요청에 필요합니다. 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
Instruction 선택사항 사용자 정의 에이전트 명령어입니다.

이 확장 프로그램을 지원하는 에이전트는 agentInstructions 키가 있는 추가 컨텍스트로 에이전트 명령어 목록을 허용합니다. 에이전트 명령어는 다음 스키마로 정의됩니다.
  • Name: 명령어의 이름입니다. 일반적으로 파일 이름입니다.
  • Definition: 명령어 정의
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/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/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/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는 데이터 엔지니어링 에이전트를 사용하기 위한 다음과 같은 핵심 엔드포인트를 제공합니다.

작업 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

추가 리소스

요청 및 응답 구조의 메서드, 엔드포인트, 유형 정의에 대한 자세한 설명은 데이터 엔지니어링 에이전트 API REST 참조를 참고하세요.