חיבור מעבד התוסף Apigee ל-Agent Gateway

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

בדף הזה מוסבר איך לחבר את מעבד התוספים של Apigee אל Agent Gateway, כדי שמדיניות Apigee תחול על הקריאות שסוכן AI מבצע למודל שלו, לכלים שלו ולשרתי Model Context Protocol‏ (MCP) שבהם הוא משתמש – בלי לשנות את הסוכן.

Agent Gateway הוא נקודת הכניסה והיציאה של תעבורת נתונים של סוכן ברשת. הוא לא מאזן עומסים, ולכן הוא לא משתמש בתוסף תעבורה. במקום זאת, שער הכניסה מעביר את ההרשאה לתוסף הרשאות, ואתם מגדירים את מעבד התוסף כתוסף הזה. אחרי ההתחברות, השער שולח כל בקשה של סוכן ותגובה ל-Apigee לעיבוד, ו-Apigee מחזיר פסק דין.

באיור הבא מוצגים המשאבים שיוצרים בדף הזה, והנתיב של בקשה מסוימת של סוכן דרכם:

איור 1. רכיבים וזרימת בקשות כשמעבד התוסף Apigee הוא תוסף ההרשאה של Agent Gateway.

באיור 1, בקשה מטופלת באופן הבא:

1. הסוכן שולח בקשת HTTPS רגילה למודל, לכלי או לשרת MCP. הנציג משויך לשער כשהוא נוצר, ולא צריך לבצע בו שינויים.
2. השער מחזיק את הבקשה וקורא לתוסף ההרשאה כדי לקבל פסיקה.
3. הקריאה יוצאת דרך מחבר הרשת, כך שהיא מתחילה בתוך רשת ה-VPC.
4. אזור ה-DNS הפרטי מתרגם את שם המארח של ה-callout לכתובת ה-IP הפנימית של נקודת הקצה (endpoint) של Private Service Connect.
5. נקודת הקצה מעבירה את הקריאה לשירות המצורף של מופע Apigee.
6. קבוצת הסביבה מעבירה את הקריאה ל-proxy ללא יעד לפי שם המארח שלה, שבו המדיניות שלכם מופעלת.
7. ה-Proxy מחזיר פסק דין לשער. ‫Apigee אף פעם לא מעביר את התנועה של הסוכן – ל-proxy אין יעד.
8. אם פסק הדין מאשר את הבקשה, השער שולח את הבקשה המקורית ליעד שלה.

הערכים AuthzPolicy ו-AuthzExtension באיור 1 הם הגדרות ולא תנועה: המדיניות מצרפת את התוסף לשער, ושמות התוספים מציינים את ה-proxy של מעבד התוספים שפועל. אתם יוצרים את שניהם בהגדרת תוסף ההרשאה.

כדי לחבר את מעבד התוספים למאזן עומסים, אפשר לעיין במאמר תחילת העבודה עם מעבד התוספים של Apigee.

בקטעים הבאים מפורטים השלבים:

• הגדרת מעבד התוסף Apigee.
• חיבור של Agent Gateway ל-Apigee.
• הגדרת תוסף ההרשאות
• אימות החיבור

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

לפני שמתחילים, צריך לבצע את המשימות הבאות:

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. מתקינים את Google Cloud CLI.

   אחרי שמתקינים את Google Cloud CLI, מריצים את הפקודה gcloud components update כדי לקבל את הרכיבים העדכניים ביותר של gcloud.

2. אם עדיין לא עשיתם את זה, אתם צריכים להקצות מופע של Apigee.

   נכנסים לדף Apigee Instances במסוף Google Cloud .

   כניסה לדף Apigee Instances

3. פורסים Agent Gateway באותו אזור שבו נמצא מופע Apigee, עם governedAccessPath שמוגדר ל-AGENT_TO_ANYWHERE, כדי שהשער ישלוט בתעבורה היוצאת של הסוכן. מידע נוסף זמין במאמר בנושא הגדרת Agent Gateway.

   אפשר לעדכן את הגדרות הרשת של השער הזה בהמשך, בקטע עדכון Agent Gateway, אחרי שתחום ה-DNS נוצר.

4. מוודאים שיש לכם VPC ורשת משנה שגם Agent Gateway וגם נקודת הקצה של Private Service Connect יכולים להשתמש בהם.

   כניסה אל VPC Networks

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לחיבור של מעבד התוסף Apigee ל-Agent Gateway, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

• ליצור ולנהל משאבי Apigee: אדמין ארגוני ב-Apigee (roles/apigee.admin) בארגון
• ליצור ולנהל הרחבות שירות: אדמין של הרחבות שירות (roles/networkservices.serviceExtensionsAdmin) בארגון
• ליצור ולנהל מדיניות הרשאות: אדמין אבטחת רשת (roles/networksecurity.admin) בארגון
• יצירה וניהול של משאבי רשת, כולל נקודות קצה של Private Service Connect ו-DNS: אדמין רשת ב-Compute (roles/compute.networkAdmin) בארגון

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

הגדרה של משתני סביבה

מגדירים את משתני הסביבה הבאים כדי לזהות את המשאבים שיצרתם בקטע לפני שמתחילים. בכל אחד מהסעיפים הבאים בדף הזה מוגדרים המשתנים הנוספים שנדרשים, בנקודה שבה יוצרים את המשאב שמופיע בשם שלהם.

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET
export GATEWAY=GATEWAY

כאשר:

• ‫PROJECT_ID הוא מזהה הפרויקט שמכיל את מופע Apigee.
• ‫REGION הוא ה Google Cloud אזור של מכונת Apigee.
• ‫INSTANCE הוא השם של מופע Apigee.
• ‫VPC_NETWORK_NAME ו-SUBNET הם רשת ה-VPC ורשת המשנה שמשמשות את Agent Gateway ואת נקודת הקצה של Private Service Connect.
• ‫GATEWAY הוא השם של Agent Gateway שפרסתם.

כדי לוודא שמשתני הסביבה מוגדרים בצורה נכונה, מריצים את הפקודה הבאה ובודקים את הפלט:

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY

בחירת שם המארח של השיחה

השער מגיע אל Apigee בשם מארח פרטי שאתם בוחרים. צריך לבחור אותו עכשיו, לפני שיוצרים משהו, כי המשאב הראשון שיוצרים – קבוצת הסביבות של Apigee – משתמש בו כשם המארח שלו, בעוד שאזור ה-DNS שמבצע את ההמרה שלו לא נוצר עד שמבצעים את הפעולה יצירת אזור DNS פרטי.

export DNS_DOMAIN=DNS_DOMAIN
export EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN

כאשר DNS_DOMAIN הוא דומיין DNS פרטי שלא צריך להיות ניתן לפענוח באינטרנט הציבורי, והוא נכתב ללא נקודה בסוף, למשל internal.example.com. התוצאה היא EXTPROC_HOST של apigee-extproc.internal.example.com. אפשר להשתמש בתווית אחרת במקום בתווית apigee-extproc, כל עוד שם המארח נשאר בתוך התווית DNS_DOMAIN.

חשוב: נעשה שימוש ב-EXTPROC_HOST בשלושה מקומות: שם המארח של קבוצת סביבות Apigee, רשומת ה-DNS הפרטי והשדות authority ו-service של תוסף ההרשאה. שלושתם חייבים להיות זהים, אחרת ה-callout לא יגיע ל-Apigee. שם המארח צריך להיות גם בתוך DNS_DOMAIN, ולכן הפקודה שלמעלה גוזרת אותו מהמשתנה הזה.

הגדרת טוקן אימות

‫

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

הערה: אם הארגון שלכם משתמש במיקום אחסון הנתונים, צריך להחליף את apigee.googleapis.com בפקודות שבדף הזה בנקודת הקצה האזורית של הארגון. מידע נוסף זמין במאמר בנושא שימוש בנקודות קצה אזוריות למיקום אחסון הנתונים.

הגדרת מעבד התוסף Apigee

נותנים שמות למשאבי Apigee שהחלק הזה יוצר:

export EXTPROC_ENV=EXTPROC_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

כאשר:

• ‫EXTPROC_ENV ו-EXTPROC_ENVGROUP הם שמות שאתם בוחרים לסביבת Apigee ולקבוצת סביבות שמוקדשות למעבד התוסף, לדוגמה extproc-env ו-extproc-envgroup. כל שם צריך לכלול בין 2 ל-32 תווים של אותיות קטנות, מספרים או מקפים, להתחיל באות ולא להסתיים במקף. שם הסביבה צריך להיות שונה מכל שם אחר של סביבה בארגון.
• ‫PROXY_NAME הוא שם שבוחרים ל-proxy של מעבד התוסף, לדוגמה extproc-authz.

ההגדרה בצד Apigee זהה להגדרה של מאזן עומסים. פועלים לפי ההוראות שבקטע הגדרת מעבד התוסף Apigee במדריך למתחילים כדי:

1. יוצרים סביבת Apigee עם המאפיין apigee-service-extension-enabled שמוגדר לערך true, מצרפים אותה למופע ויוצרים קבוצת סביבות ששם המארח שלה הוא $EXTPROC_HOST.
2. יוצרים ופורסים שרת proxy של מעבד תוספים ללא יעד בסביבה הזו.

הערה: במדריך למתחילים הזה, המשאבים האלה נקראים ENV_NAME, ENV_GROUP_NAME ו-ENV_GROUP_HOSTNAME. משתמשים ב-$EXTPROC_ENV, ב-$EXTPROC_ENVGROUP וב-$EXTPROC_HOST בהתאמה.

הערה: אם מדיניות כלשהי ב-proxy קוראת ל- Google Cloud API, צריך לפרוס את ה-proxy עם חשבון שירות על ידי הוספת ?serviceAccount=SERVICE_ACCOUNT_EMAIL לבקשת הפריסה. אחרת, הפריסה תיכשל עם השגיאה MISSING_SERVICE_ACCOUNT.

לאחר מכן מפרטים את הפריסות בסביבה:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"

יכול להיות שיהיו יותר משרת proxy אחד שפרוס בסביבה, לכן בתשובה צריך לחפש את הרשומה שבה apiProxy הוא $PROXY_NAME ולרשום את revision.

אפשר לבדוק את השרת הפרוקסי במסוף Google Cloud :

מעבר אל API Proxies

מגדירים את המשתנה הבא לגרסה הזו, שנדרשת בשלב אימות החיבור:

export REVISION=REVISION

חיבור של Agent Gateway ל-Apigee

השער מגיע אל Apigee דרך נקודת קצה (endpoint) של Private Service Connect ב-VPC, שאותה הוא מוצא על ידי פתרון של $EXTPROC_HOST באזור DNS פרטי.

חיפוש קובץ מצורף של שירות

מאתרים את קובץ השירות המצורף של מופע Apigee:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"

מגדירים את המשתנה הבא לערך serviceAttachment של המופע באזור שלכם:

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

יצירת צירוף רשת

היציאה של Agent Gateway מתבצעת אל ה-VPC שלכם דרך חיבור לרשת. בוחרים שם, למשל agent-gateway-attachment, ויוצרים אותו:

export NETWORK_ATTACHMENT=NETWORK_ATTACHMENT
gcloud compute network-attachments create $NETWORK_ATTACHMENT \
    --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC

יצירת נקודת הקצה של Private Service Connect

שומרים כתובת IP פנימית ויוצרים את נקודת הקצה (endpoint) של Private Service Connect:

gcloud compute addresses create apigee-extproc-psc-ip \
    --region=$REGION --subnet=$SUBNET --purpose=GCE_ENDPOINT
gcloud compute forwarding-rules create apigee-extproc-psc-endpoint \
    --region=$REGION --network=$VPC_NETWORK_NAME \
    --address=apigee-extproc-psc-ip \
    --target-service-attachment=$SERVICE_ATTACHMENT

נכנסים לדף Private Service Connect במסוף Google Cloud .

כניסה אל Private Service Connect

מוודאים שנקודת הקצה מדווחת על pscConnectionStatus: ACCEPTED, ומגדירים את המשתנה הבא לכתובת ה-IP שלה:

gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \
    --region=$REGION --format="value(pscConnectionStatus,IPAddress)"
export PSC_IP=PSC_IP

אם הסטטוס הוא PENDING, הפרויקט לא נמצא ב-consumerAcceptList של מופע Apigee, ואי אפשר לאשר את החיבור.

יצירת תחום DNS פרטי

יוצרים תחום DNS פרטי בשביל $DNS_DOMAIN ורשומת A שמבצעת המרה של $EXTPROC_HOST לכתובת ה-IP של נקודת הקצה:

gcloud dns managed-zones create extproc-zone \
    --dns-name=$DNS_DOMAIN. --visibility=private --networks=$VPC_NETWORK_NAME \
    --description="Apigee extension processor callout host"
gcloud dns record-sets create $EXTPROC_HOST. --type=A --ttl=300 \
    --rrdatas=$PSC_IP --zone=extproc-zone

עדכון של Agent Gateway

מעדכנים את Agent Gateway מהקטע לפני שמתחילים כדי שהתעבורה תצא דרך מחבר הרשת המצורף ותוכל לפתור את התחום שיצרתם.

זהירות: ייבוא של שער סוכנים מחליף את כל המשאב. תמיד מתחילים מההגדרה המיוצאת ועורכים אותה, במקום לכתוב קובץ חדש. אם משמיטים שדות, כמו protocols ו-registries, הם מוסרים משער הכניסה.

1. מייצאים את ההגדרות הנוכחיות:

   gcloud network-services agent-gateways export $GATEWAY \
       --location=$REGION --destination=agent-gateway.yaml

2. ב-agent-gateway.yaml, מוסיפים את הבלוק networkConfig הבא, ומחליפים כל placeholder בערך של משתנה הסביבה המתאים. הקובץ נערך ישירות, לכן לא מתבצעת כאן החלפה של משתני מעטפת:

   networkConfig:
     egress:
       networkAttachment: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT
     dnsPeeringConfig:
       domains: [ DNS_DOMAIN. ]
       targetProject: PROJECT_ID
       targetNetwork: projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

   משאירים את שאר הקובץ, כולל googleManaged.governedAccessPath, protocols ו-registries, כמו שהוא אחרי הייצוא.

3. מייבאים את ההגדרה האישית הערוכה:

   gcloud network-services agent-gateways import $GATEWAY \
       --location=$REGION --source=agent-gateway.yaml

רשימה מלאה של השדות של Agent Gateway מופיעה במאמר בנושא הגדרת Agent Gateway.

הגדרת תוסף ההרשאות

שני משאבים מקשרים את השער לשרת ה-proxy של מעבד התוספים: תוסף הרשאה שמפנה אל Apigee, ומדיניות הרשאה שמצרפת את התוסף לשער.

יצירת תוסף ההרשאה

בוחרים שם לתוסף ההרשאות, למשל apigee-authz-extension. בשדות metadata בוחרים איזה proxy של Apigee יופעל ואם גופי ההודעות יישלחו אליו:

export AUTHZ_EXT=AUTHZ_EXT
cat > authz-extension.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
authority: $EXTPROC_HOST
service: $EXTPROC_HOST
timeout: 5s
metadata:
  apigee-extension-processor: $PROXY_NAME
  apigee-request-body: 'true'
  apigee-response-body: 'true'
EOF
gcloud service-extensions authz-extensions import $AUTHZ_EXT \
    --source=authz-extension.yaml --location=$REGION

כאשר:

• ‫apigee-extension-processor בוחר את שרת ה-proxy של מעבד התוסף שמטפל בתנועה.
• ‫apigee-request-body ו-apigee-response-body מאפשרים לגשת לגוף הבקשה ולגוף התגובה בשרת ה-proxy בתור request.content ו-response.content. בלעדיהם, מדיניות שבודקת את מטען הנתונים לא מוצאת כלום.

יצירת מדיניות ההרשאות

בוחרים שם למדיניות ההרשאות, לדוגמה: apigee-content-authz-policy. המדיניות מצרפת את התוסף לשער וקובעת איזו תנועה נשלחת אל Apigee:

export AUTHZ_POLICY=AUTHZ_POLICY
cat > authz-policy.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzPolicies/$AUTHZ_POLICY
action: CUSTOM
policyProfile: CONTENT_AUTHZ
customProvider:
  authzExtension:
    resources:
    - projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
httpRules:
- to:
    operations:
    - paths:
      - prefix: "/"
target:
  resources:
  - projects/$PROJECT_ID/locations/$REGION/agentGateways/$GATEWAY
EOF
gcloud beta network-security authz-policies import $AUTHZ_POLICY \
    --source=authz-policy.yaml --location=$REGION

משתמשים בpolicyProfile: CONTENT_AUTHZ כדי לבדוק את גוף ההודעה. מדיניות REQUEST_AUTHZ בודקת רק את כותרות הבקשות.

חשוב: בדוגמה שלמעלה, כל בקשה תואמת ל-prefix: "/", ולכן כל התנועה של הסוכן נשלחת אל Apigee – כולל הסשן, הטלמטריה והקריאות לכלים. מצמצמים את ההיקף באמצעות to.operations.paths או באמצעות ביטוי Common Expression Language ‏(CEL) בשדה when, כך שרק התנועה שרוצים לנהל תעבור עיבוד.

אימות החיבור

כדי ליצור תנועה, צריך סוכן שהיציאה שלו מנוהלת על ידי השער הזה. סוכן מקושר ל-Agent Gateway כשהוא נוצר, על ידי הגדרת התצורה של Agent Gateway שלו ל-$GATEWAY. אי אפשר להשתמש בחיבור באמצעות בקשת HTTP ישירה ל-Agent Gateway. מידע נוסף זמין במאמר בנושא הגדרת Agent Gateway.

מתחילים סשן לניפוי באגים ב-Apigee בשרת ה-proxy של מעבד התוסף, ואז שולחים בקשה אחת דרך הסוכן:

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/apis/$PROXY_NAME/revisions/$REVISION/debugsessions?timeout=600" \
  -d '{"count":15,"tracesize":5120,"filter":"(request.uri Like \"*generateContent*\")"}'

הערה: כל פנייה של סוכן יוצרת כמה טרנזקציות, כי גם הסשן של הסוכן וגם קריאות הטלמטריה עוברים דרך השער. כדי ללכוד רק את תעבורת הנתונים שרוצים לבדוק, צריך להשתמש בשדה filter. אחרת, יכול להיות שהמאגר יתמלא לפני שהבקשה שמחפשים תגיע.

בעסקאות שתועדו, מוודאים ש:

• כתובת ה-URL של הבקשה היא הכתובת שאליה הסוכן התקשר, כמו נקודת הקצה של המודל או מארח של כלי, ולא נתיב בסיסי של Apigee.
• ‫request.content ו-response.content מאוכלסים, מה שמאשר שהמטא-נתונים של הגוף בתוסף ההרשאה פועלים.

אם לא מופיעות טרנזקציות, צריך לוודא ששם המארח של קבוצת הסביבות, רשומת ה-DNS והשדות authority ו-service של התוסף הם $EXTPROC_HOST, שנקודת הקצה של Private Service Connect מדווחת על ACCEPTED וש-governedAccessPath של השער הוא AGENT_TO_ANYWHERE.

המאמרים הבאים

• סקירה כללית על מעבד התוספים של Apigee
• כדי להתחיל, צריך להשתמש במעבד התוספים של Apigee במאזן עומסים.