Data Engineering Agent API: Build data pipelines with an agent

אתם יכולים להשתמש ב-Data Engineering Agent API, שאפשר לגשת אליו דרך geminidataanalytics.googleapis.com, כדי ליצור, לשנות ולנהל צינורות נתונים לטעינה ולעיבוד של נתונים ב-BigQuery. ה-API משתמש בפרוטוקול A2A שמאפשר להשתמש בהנחיות בשפה טבעית כדי ליצור ולערוך צינורות נתונים לצרכים של הנדסת נתונים.

מידע נוסף על Data Engineering Agent זמין במאמר שימוש ב-Data Engineering Agent כדי לבנות ולשנות צינורות נתונים.

איך Gemini for Google Cloud ‎ משתמש בנתונים שלכם, ובאילו מקרים.

לפני שמתחילים

לפני שמשתמשים בממשק Data Engineering Agent API, צריך לבצע את השלבים שמפורטים בקטעים הבאים.

הפעלת ממשקי ה-API

מוודאים שהפעלתם את ממשקי ה-API הנדרשים ושיש לכם את ההרשאות הנדרשות. מידע נוסף זמין במאמר בנושא הפעלת ממשקי ה-API הנדרשים.

התקנה של ספריות לקוח

מתקינים את ספריות הלקוח הבאות:

מידע נוסף זמין במאמר בנושא פרוטוקול Agent2Agent (A2A).

תוספים נתמכים של A2A

הסוכן Data Engineering Agent תומך בתוספים הבאים של A2A, שחלקם נדרשים כשמבצעים אינטראקציה עם הסוכן Data Engineering Agent.

שם התוסף דרישה תיאור URI
GcpResource חובה מזהה המשאב Google Cloud של המשאב שהסוכן פועל עליו. חובה לציין את הערך הזה בכל בקשה. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken אופציונלי תוסף להיסטוריית שיחות רב-שלביות בתור טוקן שיחה אטום.

התוסף הזה נדרש כדי להמשיך שיחות רב-שלביות ממצב קודם. כדי להמשיך, מעתיקים את ערך אסימון השיחה בשדה המטא-נתונים של התגובה הקודמת מהסוכן, וכוללים אותו בשדה המטא-נתונים של הבקשה הבאה לסוכן.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel אופציונלי רמת ההודעה לשליטה בנראות של עדכוני הודעות בלקוח.

הסוכן שתומך בתוסף הזה מצרף את messageLevel לכל message כדי לאפשר ללקוח לשלוט בגישה.		 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, הלקוח צריך לכלול את A2A-Extensions הכותרת בבקשת ה-HTTP לסוכן. הערך הוא רשימה מופרדת בפסיקים של כתובות URI של תוספים להפעלה.

כדי להשתמש ב-Data Engineering Agent A2A API, צריך להפעיל את התוסף GcpResource.

בדוגמה הבאה מוצגת בקשת HTTP להפעלת התוסף 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"
}

התגובה עשויה להיות דומה לזו.

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 מספק את נקודות הקצה הבאות לשימוש ב-Data Engineering Agent:

פעולה שיטת HTTP נקודת קצה (endpoint) תיאור
קבלת כרטיס סוכן 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.

מקורות מידע נוספים

תיאורים מפורטים של רכיבי ה-method, נקודות הקצה והגדרות הסוגים של מבני הבקשות והתגובות מופיעים במאמר הפניית REST API של Data Engineering Agent.