১. ভূমিকা
যে এজেন্টের কাছে নিজের ক্রেডেনশিয়াল আছে এবং যার কাছে অনেক বেশি অনুমতি আছে, সে সকলের ডেটা দেখতে পায়। এই কোডল্যাবে আপনি এমন একটি এজেন্ট তৈরি করবেন যা সাইন-ইন করা ব্যবহারকারীর নিজস্ব ক্রেডেনশিয়াল দিয়ে থার্ড-পার্টি API কল করে, যাতে সেই ব্যক্তি ঠিক যা দেখতে পান, এজেন্টও তাই দেখতে পায় এবং তার বেশি কিছু নয়।
আপনি এটি Google Agent Development Kit (ADK) এবং Gemini Enterprise-এর সাহায্যে তৈরি করবেন।
বিশেষত, আপনি কীভাবে এমন একটি দ্বৈত-পরিচয় আর্কিটেকচার ডিজাইন করবেন তা শিখবেন যেখানে:
- এজেন্ট নিজের হয়ে কাজ করে (এজেন্ট পরিচয়): SPIFFE-এর মাধ্যমে সুরক্ষিত এজেন্ট পরিচয় ব্যবহার করে, এজেন্ট Auth Manager-কে ইনভোক করে, টেলিমেট্রি সেভ করে এবং Google Cloud API-কে কল করে।
- এজেন্ট ব্যবহারকারীর হয়ে কাজ করে (ব্যবহারকারীর দ্বারা অ্যাসাইন করা পরিচয়): GitHub-এর মতো এক্সটার্নাল রিসোর্স অ্যাক্সেস করতে, এজেন্ট ব্যবহারকারীর ক্রেডেনশিয়াল ব্যবহার করে নিরাপদে টুল কোয়েরি করার জন্য ৩-লেগড OAuth (3LO) সম্মতি ফ্লো ট্রিগার করে।
এটি করতে, আপনি কীভাবে:
- GitHub-এর Model Context Protocol (MCP) সার্ভারের সাথে কানেক্ট করে এমন ADK এজেন্ট তৈরি করা।
- Google Cloud Auth Manager ব্যবহার করে এজেন্টের টুলকে স্ট্যাটিক GitHub PAT (ব্যক্তিগত অ্যাক্সেস টোকেন) থেকে ৩-লেগড OAuth (3LO) ফ্লোতে আপডেট করুন।
- এজেন্ট রানটাইমে নিরাপদে এজেন্ট ডিপ্লয় করুন এবং এজেন্ট আইডেন্টিটি প্রোভিশন করুন।
- ব্যবহারকারীর হয়ে টোকেন ভল্টে এজেন্টের পরিচয় অ্যাক্সেস দেওয়ার জন্য IAM ভূমিকা কনফিগার করুন।
- Google Cloud-এ Auth Manager-এর জন্য এন্ড-টু-এন্ড 3LO ফ্লো বুঝুন।
পূর্বশর্ত
শুরু করার আগে, আপনার কাছে এগুলি আছে কিনা তা ভালোভাবে দেখে নিন:
- বিলিং চালু করা Google Cloud প্রোজেক্ট।
- আপনার লোকাল মেশিনে Google Cloud SDK (
gcloudCLI) ইনস্টল করা এবং আপনার প্রোজেক্টে যাচাই করা। 586.0.0 বা এর পরের যেকোনও ভার্সন প্রয়োজন —gcloud components updateচালান। - লোকাল মেশিনে Python 3.10 থেকে 3.13 ইনস্টল করা আছে।
uvপ্যাকেজ ম্যানেজার ইনস্টল করা হয়েছে (pip install uv)।- OAuth অ্যাপ্লিকেশন রেজিস্টার করতে ও টোকেন তৈরি করতে GitHub অ্যাকাউন্ট। আপনার GitHub অ্যাকাউন্ট না থাকলে, আপনি থ্রি-লেগড OAuth 2.0 কাজ করে এমন যেকোনও থার্ড-পার্টি MCP সার্ভার ব্যবহার করতে পারেন।
২. প্রোজেক্ট সেট-আপ
১. Google Cloud-এ যাচাইকরণ
এই ল্যাব চলাকালীন Agent Runtime-এ ডেপ্লয় করা, এজেন্ট পরিচয় প্রদান করা এবং যাচাইকরণ ম্যানেজার কনফিগার করার জন্য আপনার এনভায়রনমেন্টে প্রয়োজনীয় অনুমতি আছে কিনা তা নিশ্চিত করতে, আপনার স্থানীয় কমান্ড লাইন থেকে Google Cloud-এ যাচাই করুন:
অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়াল (ADC) কনফিগার করতে, আপনার Google Cloud অ্যাকাউন্টে লগ-ইন করার জন্য নিম্নলিখিত কমান্ডগুলি রান করুন:
gcloud auth login
gcloud auth application-default login
২. প্রয়োজনীয় Google Cloud পরিষেবা চালু করা
এই ল্যাব চালানোর জন্য আপনার Google Cloud প্রোজেক্টে প্রয়োজনীয় API চালু করুন। আপনার টার্মিনালে নিম্নলিখিত কমান্ড রান করুন:
gcloud services enable \
agentidentity.googleapis.com \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com
এই কমান্ডটি এক্সিকিউট করতে এক মিনিট সময় লাগতে পারে; এটি সম্পূর্ণ হয়ে গেলে, API অ্যাক্টিভ আছে তা কনফার্ম করে কমান্ড প্রম্পটে ফিরে আসবে।
৩. এজেন্ট CLI ইনস্টল করুন এবং প্রোজেক্ট সেট-আপ করুন
agents-cli হল কমান্ড-লাইন টুল যা Gemini Enterprise-এ ADK এজেন্ট স্ক্যাফোল্ড, ম্যানেজ, টেস্ট ও ডিপ্লয় করতে ব্যবহার করা হয়। এটি লোকালি ইনস্টল করুন:
uvx google-agents-cli setup
আপনার ইনস্টলেশন যাচাই করুন:
agents-cli --help
উপলভ্য কমান্ড (যেমন deploy, run ও status) সহ CLI-এর সহায়তা মেনু আপনার দেখা উচিত।
প্রাথমিক প্রোজেক্ট স্ক্যাফোল্ডিং তৈরি করা। আপনি একটি লোকাল প্রোটোটাইপ দিয়ে শুরু করবেন এবং এজেন্ট রানটাইম ডিপ্লয়মেন্টের জন্য পরে সেটি উন্নত করবেন:
agents-cli create secure-agent-demo --prototype --yes
এর ফলে secure-agent-demo ডিরেক্টরি তৈরি হয়, যার মধ্যে আপনার ফাউন্ডেশনাল এজেন্ট কোড, ডিপেন্ডেন্সি ও টেস্ট ফাইল থাকে।
৪. প্রয়োজনীয় ADK এক্সট্রা যোগ করুন
জেনারেট করা pyproject.toml শিপ google-adk[gcp,otel-gcp]-এ দুটি এক্সট্রা নেই যা এই এজেন্টের প্রয়োজন: mcp GitHub টুলসেটের জন্য এবং agent-identity ল্যাবে পরে Auth Manager-এর জন্য। secure-agent-demo/pyproject.toml খুলুন এবং google-adk লাইনটি পরিবর্তন করে এটি করুন:
"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",
তারপরে ইনস্টল করুন:
cd secure-agent-demo
agents-cli install
৩. এজেন্ট তৈরি ও পরীক্ষা করা
১. এজেন্ট তৈরি করা
আপনার প্রোজেক্টের মধ্যে, agent.py ফাইলে নিম্নলিখিত কোডটি পরিবর্তন করুন:
# app/agent.py
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
from app.tools import github_toolset
import os
import google.auth
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.
Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""
root_agent = Agent(
name="root_agent",
model=Gemini(
model="gemini-3.8-flash",
retry_options=types.HttpRetryOptions(attempts=3),
),
instruction=INSTRUCTION,
tools=[github_toolset()],
)
app = App(
root_agent=root_agent,
name="app",
)
এই ফাইলটি এজেন্টের তিনটি মূল উপাদানকে সংজ্ঞায়িত করে:
- সিস্টেম নির্দেশাবলী (
INSTRUCTION): পার্সোনা সেট করে, GitHub ট্রায়েজের জন্য অ্যাসিস্ট্যান্টের স্কোপ নির্ধারণ করে এবং কঠোর নিরাপত্তা সংক্রান্ত নিয়ম (যেমন, শুধু-পঠনযোগ্য অ্যাক্সেস এবং কোনও সমস্যা হলে ব্যবহারকারীকে যাচাইকরণ করতে বলা) প্রয়োগ করে। - এজেন্ট কনফিগারেশন (
root_agent):gemini-3.8-flashমডেল ব্যবহার করে ADKAgentইনস্ট্যানশিয়েট করে, HTTP আবার চেষ্টা করার লজিক কনফিগার করে এবং এজেন্টকে GitHub টুলসেট প্রদান করে। - অ্যাপ র্যাপার (
app): ADKAppকন্টেনারে মূল এজেন্টকে এনক্যাপসুলেট করে, এটি এজেন্ট রানটাইমে ডিপ্লয় করার উপযুক্ত করে তোলে।
২. GitHub MCP টুল যোগ করা
মডেল কন্টেক্সট প্রোটোকল (MCP)-এর মাধ্যমে এজেন্ট GitHub-এর সাথে কানেক্ট করে। MCP গেটওয়ে কানেকশন প্যারামিটার রেজিস্টার করতে app/ ফোল্ডারের মধ্যে tools.py নামের নতুন ফাইল তৈরি করুন। নিচে দেওয়া কোডটি কপি-পেস্ট করুন:
# app/tools.py
from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
def github_toolset() -> McpToolset:
"""Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url=GITHUB_MCP_URL,
headers={
"Authorization": f"Bearer {GITHUB_TOKEN}",
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
)
)
এই ফাংশন এমন একটি টুল তৈরি করে যা GitHub-এর MCP সার্ভারকে কল করে:
- MCP টুলসেট (
McpToolset): কল করা যায় এমন এজেন্ট টুল হিসেবে GitHub-এর ক্ষমতা ডায়নামিক পদ্ধতিতে খুঁজে পায় ও রেজিস্টার করে। - কানেকশন প্যারামিটার (
StreamableHTTPConnectionParams): টুলসেটকে GitHub-এর পাবলিক MCP গেটওয়ের দিকে নির্দেশ করে। - অনুমোদন হেডার: বিয়ারার টোকেন হিসেবে
GITHUB_TOKENইনজেক্ট করে এবং ট্রান্সপোর্ট লেভেলে সরাসরি রিড-ওনলি মোড (X-MCP-Readonly: true) প্রয়োগ করে।
৩. GitHub PAT (ব্যক্তিগত অ্যাক্সেস টোকেন) ব্যবহার করে লোকালি পরীক্ষা করা
স্ট্যাটিক ক্রেডেনশিয়াল সহ এজেন্টকে লোকালি রান করাতে:
- GitHub ব্যক্তিগত অ্যাক্সেস টোকেন তৈরি করুন। আপনার রিপোজিটরি পড়ার অ্যাক্সেস দিন, তা না হলে এজেন্ট শুধুমাত্র সর্বজনীন ডেটা দেখতে পাবে এবং নিচের প্রম্পটটি কোনও উত্তর দেবে না।
- আপনার এনভায়রনমেন্টে এটি সেট করুন:
export GITHUB_TOKEN="your_github_pat_here" secure-agent-demoফোল্ডারে নেভিগেট করুন। রান করুন:cd secure-agent-demo agents-cli playground- প্লেগ্রাউন্ড ইন্টারফেস খুলুন, ড্রপডাউন থেকে "অ্যাপ" ফোল্ডারটি বেছে নিন। চ্যাটবক্সে
"Fetch my contributions across my private repositories over the last 6 months"টাইপ করুন এবং এজেন্ট GitHub টুল কল করে আপনার ব্যক্তিগত রিপোজিটরি থেকে ডেটা রিটার্ন করছে কিনা তা যাচাই করুন।
৪. Auth Manager কনফিগার করা
প্রোটোটাইপিংয়ের জন্য স্ট্যাটিক ক্রেডেনশিয়াল (যেমন, PAT) হার্ডকোড করা সুবিধাজনক হলেও, এটি প্রোডাকশন অ্যাপ্লিকেশনকে ক্রেডেনশিয়াল লিক হওয়া, ম্যানুয়াল টোকেন রিফ্রেশ ডাউনটাইম এবং ক্লাউড-নেটিভ অ্যাক্সেস কন্ট্রোল না থাকার মতো ঝুঁকির মুখে ফেলে দেয়।
এর সমাধান করতে, Google Cloud এজেন্ট আইডেন্টিটি অথ ম্যানেজার প্রদান করে। এজেন্ট আইডেন্টিটি অথ ম্যানেজারের মাধ্যমে ক্রেডেনশিয়াল সুরক্ষিত রাখা যায়। এটি একটি ক্রেডেনশিয়াল ভল্ট। এটি এজেন্টদের API কী বা OAuth ক্লায়েন্ট আইডি এবং সিক্রেট ব্যবহার করে যাচাই করতে দেয় অথবা ব্যবহারকারীর হয়ে OAuth ডেলিগেশনের মাধ্যমে ব্যবহারকারীর অ্যাক্সেস টোকেন ব্যবহার করে যাচাই করতে দেয়।
Auth Manager-এর মধ্যে, আপনি এমন সব অথেন্টিকেশন প্রোভাইডার কনফিগার করেন যা নির্দিষ্ট থার্ড-পার্টি অ্যাপ্লিকেশনের জন্য অথেন্টিকেশন ধরন ও ক্রেডেনশিয়াল নির্ধারণ করে। অনুমোদন প্রদানকারী আঞ্চলিক হয় এবং আপনি যে অঞ্চলে এজেন্ট ডেপ্লয় করছেন সেই অঞ্চলের সাথে মিল থাকতে হবে। সম্পূর্ণ Auth Manager ওয়ার্কফ্লো নিম্নলিখিতভাবে কাজ করে:
- ডায়নামিক সম্মতি ইন্টারসেপশন: এজেন্ট যখন কোনও ব্যবহারকারীর হয়ে টুল এক্সিকিউট করার চেষ্টা করে, তখন ADK আগে থেকে থাকা বৈধ ক্রেডেনশিয়ালের জন্য Auth Manager চেক করে। কোনওটি না থাকলে, Auth Manager একটি ৩-লেগড OAuth (3LO) সম্মতি ফ্লো শুরু করার জন্য একটি অনুমোদনের URL রিটার্ন করে।
- নিরাপদ ভল্ট স্টোরেজ: এন্ড-ইউজার অ্যাপ্লিকেশনকে অনুমোদন করার পরে, Auth Manager অটোমেটিক OAuth কলব্যাক ইন্টারসেপ্ট করে এবং এর ফলে প্রাপ্ত ব্যবহারকারীর অ্যাক্সেস ও রিফ্রেশ টোকেন Google-ম্যানেজ করা নিরাপদ ক্রেডেনশিয়াল ভল্টে সেভ করে।
- অটোমেটিক টোকেন লাইফসাইকেল: ব্যাকগ্রাউন্ডে টোকেনের মেয়াদ শেষ হওয়া ও টোকেন পরিবর্তন করা সংক্রান্ত বিষয়গুলি Auth Manager সম্পূর্ণভাবে ম্যানেজ করে, এর ফলে ম্যানুয়ালি টোকেন রিফ্রেশ করার লজিক বা ডাউনটাইমের প্রয়োজন হয় না।
- সিক্রেট-ফ্রি টুল এক্সিকিউশন: পরবর্তী অ্যাকশনের জন্য, এজেন্ট (এর SPIFFE এজেন্ট আইডেন্টিটির মাধ্যমে প্রমাণীকরণ করে) রানটাইমে Auth Manager-এর থেকে ব্যবহারকারীর ডেলিগেট করা অ্যাক্সেস টোকেনের জন্য ডায়নামিক অনুরোধ করে, ক্লায়েন্ট এবং এজেন্ট কোড উভয়ই সম্পূর্ণ সিক্রেট-ফ্রি রাখে।
ধাপ ক: যাচাইকরণ পরিষেবা প্রদানকারী হিসেবে GitHub কনফিগার করা
আপনার Google Cloud প্রোজেক্টে GitHub অথেন্টিকেশন প্রদানকারী তৈরি করতে, নিম্নলিখিত gcloud কমান্ডটি রান করুন। আপনি পরে ক্লায়েন্ট আইডি ও সিক্রেট প্রদান করেন: এই প্রদানকারীর কলব্যাক URL না জানা পর্যন্ত GitHub সেগুলি ইস্যু করবে না।
gcloud agent-identity auth-providers create github-oauth-provider \
--project="${PROJECT_ID}" \
--location="us-central1" \
--three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
--three-legged-oauth-token-url="https://github.com/login/oauth/access_token"
জেনারেট করা OAuth রিডাইরেক্ট URL পেতে প্রদানকারীর বিবরণ দিন:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="${PROJECT_ID}" \
--location="us-central1"
ফিল্ডটি হল redirectUrl, যা authProviderTypeParams.threeLeggedOauth-এর মধ্যে নেস্ট করা আছে। সরাসরি এটি পড়তে:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="${PROJECT_ID}" --location="us-central1" \
--format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"
এটি https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback-এর মতো দেখতে।
ধাপ খ: GitHub-এ OAuth অ্যাপ রেজিস্টার করা
- GitHub ডেভেলপার সেটিংস পৃষ্ঠায় নেভিগেট করুন এবং নতুন OAuth অ্যাপ রেজিস্টার করুন বিকল্পে ক্লিক করুন।
- হোমপেজ URL-এর জন্য, আপনার ফ্রন্ট-এন্ড অ্যাপ্লিকেশনের URL লিখুন (যেমন,
http://localhost:8501লোকাল প্রোটোটাইপিংয়ের জন্য। পরে আপনি এটি পরিবর্তন করে প্রোডাকশনে আপনার ডেপ্লয় করা URL করতে পারবেন। - আগের ধাপে
redirectUrlথেকে পাওয়া রিডাইরেক্ট URI সেট করুন। - অ্যাপ্লিকেশন রেজিস্টার করুন বিকল্পে ক্লিক করুন, তারপর নতুন ক্লায়েন্ট সিক্রেট তৈরি করুন বিকল্পে ক্লিক করুন এবং ক্লায়েন্ট আইডি ও ক্লায়েন্ট সিক্রেট, দুটিই সেভ করুন।
ধাপ গ: অথ প্রদানকারীর কাছে GitHub ক্রেডেনশিয়াল যোগ করুন
আপনার প্রোজেক্ট আইডি, ক্লায়েন্ট আইডি ও ক্লায়েন্ট সিক্রেট পরিবর্তন করে এই কমান্ড রান করান:
gcloud agent-identity auth-providers update github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
--three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"
কমান্ডটি clientId সহ প্রদানকারীর উত্তর দেয়; সিক্রেটটি উত্তর দেয় না।
👉 এই ধাপটি সম্পূর্ণ করার পরে, আপনার GitHub OAuth অ্যাপ্লিকেশন ক্রেডেনশিয়ালের সাথে আপনার Google Cloud Auth Manager এখন সম্পূর্ণ কনফিগার করা হয়েছে, যা সম্মতি ও টোকেন লাইফসাইকেল ম্যানেজ করার জন্য Google Cloud-কে নিরাপদ ভল্ট হিসেবে সেট-আপ করে।
৫. PAT টোকেন থেকে Auth Manager-এ পরিবর্তন করা
Auth Manager সম্পূর্ণ কনফিগার করা হয়ে গেলে, পরবর্তী ধাপ হল এজেন্টের টুল কোড আপডেট করা। নিচে দেওয়া কোড দিয়ে আপনার app/tools.py পরিবর্তন করুন।
👉 নিচে দেওয়া OAUTH_PROVIDER_NAME ভেরিয়েবলে প্রোজেক্ট আইডি ও লোকেশন পরিবর্তন করুন।
# app/tools.py
from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())
# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"
# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
"OAUTH_CONTINUE_URI",
"http://localhost:8501/validateUserId"
)
def github_toolset() -> McpToolset:
"""Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
auth_scheme = GcpAuthProviderScheme(
name=OAUTH_PROVIDER_NAME,
# Required to read private repositories. Auth Manager currently supports a
# single scope for GitHub.
scopes=["repo"],
continue_uri=OAUTH_CONTINUE_URI,
)
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://api.githubcopilot.com/mcp/",
headers={
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
),
auth_scheme=auth_scheme,
)
টুল কোড বোঝা
প্রধান পরিবর্তন হল auth_scheme। টুলসেটের সাথে এটি অ্যাটাচ করার অর্থ হল, এজেন্ট যখনই GitHub-এ কল করে, ADK প্রথমে সেই ব্যবহারকারীর টোকেনের জন্য Auth Manager-কে জিজ্ঞাসা করে — এবং এখনও কোনও টোকেন না থাকলে, এটি ব্যর্থ না হয়ে ব্যবহারকারীকে সাইন-ইন করার জন্য প্রম্পট করে। হার্ডকোড করা GITHUB_TOKEN সম্পূর্ণভাবে সরিয়ে দেওয়া হয়েছে।
৬. এজেন্ট রানটাইমে এজেন্ট ডিপ্লয় করা
আমরা এখন GitHub MCP টুল আপডেট করে Auth Manager ব্যবহার করছি, এর পরের ধাপ হল Agent Runtime-এ এজেন্ট ডিপ্লয় করা। এজেন্ট আইডেন্টিটি চালু করে এটি ডেপ্লয় করলে এজেন্টের জন্য অনন্য SPIFFE আইডি প্রদান করা হয়।
প্রোজেক্টের জন্য ডেপ্লয়মেন্ট কনফিগারেশন ইনিশিয়ালাইজ করার মাধ্যমে শুরু করা যাক। টার্মিনালে রান করান:
agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes
এই কমান্ড ADK-এর সাথে মানানসই হওয়ার জন্য আপনার প্রোজেক্ট স্ট্রাকচার পরিদর্শন করে, অন্তর্নিহিত কন্টেনার প্যাকেজিং কনফিগারেশন প্রস্তুত করে এবং ডিফল্ট ডেপ্লয়মেন্ট সেটিংস সহ আগে থেকে পূরণ করা আপনার প্রোজেক্ট রুটে একটি agents-cli-manifest.yaml ফাইল তৈরি করে।
👉 নতুন তৈরি করা agents-cli-manifest.yaml ফাইল খুলুন এবং আপনার এজেন্টের ডিপ্লয়মেন্ট আপনার অথেন্টিকেশন প্রদানকারীর মতো একই অঞ্চলে হয়েছে কিনা তা নিশ্চিত করতে region ফিল্ডটি us-central1 হিসেবে যাচাই বা আপডেট করুন:
region: "us-central1"
এজেন্ট আইডেন্টিটি সহ এজেন্ট ডিপ্লয় করা
adk deploy agent_engine-এর মাধ্যমে ডিপ্লয় করুন। এটি এজেন্টকে নিজস্ব এজেন্ট আইডেন্টিটি প্রদান করে — এটি এই ডিপ্লয়মেন্টের সাথে সম্পর্কিত একটি অনন্য, SPIFFE-ব্যাকড ক্রিপ্টোগ্রাফিক আইডেন্টিটি, যা এজেন্ট Auth Manager এবং অন্যান্য Google Cloud পরিষেবায় নিজেকে প্রমাণ করার জন্য ব্যবহার করে।
👉 এইসব কমান্ড চালানোর আগে YOUR_PROJECT_ID পরিবর্তন করুন:
# Request a SPIFFE-backed Agent Identity for this deployment
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json
# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
--output-file app/requirements.txt
uv run adk deploy agent_engine app \
--project="YOUR_PROJECT_ID" \
--region="us-central1"
কন্টেনার তৈরি ও আপলোড করতে কয়েক মিনিট সময় লাগে। সম্পূর্ণ হয়ে গেলে, CLI, ডিপ্লয় করা রিসোর্সের নাম প্রিন্ট করে। reasoningEngines/ENGINE_ID ভ্যালু লিখে রাখুন, কারণ আপনার এজেন্টকে অনুমোদন করতে এবং UI ক্লায়েন্টকে সেটির দিকে পয়েন্ট করতে এটি প্রয়োজন হবে।
এজেন্টের পরিচয় অনুমোদন করা
যেহেতু আপনার এজেন্ট এখন ক্লাউডে চলছে, তাই Auth Manager-এ সেভ করা ক্রেডেনশিয়াল অ্যাক্সেস করার জন্য এটির অনুমতি প্রয়োজন। ডিফল্ট হিসেবে, এজেন্টের SPIFFE আইডেন্টিটির এক্সটার্নাল ক্লাউড রিসোর্সে কোনও অ্যাক্সেস নেই।
অন অথ প্রোভাইডার রিসোর্স roles/agentidentity.user রোলটি আপনার এজেন্টের আইডেন্টিটিকে দিতে, নিম্নলিখিত gcloud কমান্ডটি রান করুন। এটি আপনার এজেন্টকে ভল্ট থেকে ব্যবহারকারীর টোকেন অনুরোধ করার জন্য প্রয়োজনীয় সঠিক অনুমতি দেয় এবং এর বাইরে কোনও অনুমতি দেয় না।
👉 YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER ও YOUR_ENGINE_ID পরিবর্তন করুন (উপরে ডিপ্লয় আউটপুটে ইঞ্জিন আইডি দেওয়া আছে)।
YOUR_ORG_ID পেতে, নিচের কমান্ডটি রান করুন:
gcloud projects get-ancestors $(gcloud config get-value project) \
--filter="type=organization" \
--format="value(id)"
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"
এখন, পরিষেবা প্রদানকারীর কাছে আপনার নিজের অ্যাকাউন্টকে একই ভূমিকা দিন। পরবর্তী ধাপে আপনি যে UI ক্লায়েন্ট রান করান সেটি আপনার অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়ালের সাথে ক্রেডেনশিয়াল-ফাইনালাইজেশন API কল করে, তাই এটি না থাকলে agentidentity.authProviders.retrieveCredentials-এ কনসেন্ট ফ্লো 403 সহ ব্যর্থ হয়:
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="user:YOUR_EMAIL_ADDRESS"
৭. 3LO সম্মতি ফ্লো বোঝা
এখন যেহেতু এজেন্টকে নিরাপদ এজেন্ট আইডেন্টিটি সহ এজেন্ট রানটাইমে ডিপ্লয় করা হয়েছে, তাই পরবর্তী ধাপ হল ব্যবহারকারীদের সাথে চ্যাট করার জন্য কাস্টম ফ্রন্টএন্ড ইন্টারফেস প্রদান করা। এর চেয়েও গুরুত্বপূর্ণ বিষয় হল, যাচাইকরণ লুপ সম্পূর্ণ করতে Google Cloud যাচাইকরণ ম্যানেজারের ক্লায়েন্ট অ্যাপ্লিকেশন কলব্যাক হ্যান্ডলার প্রয়োজন হয়।
Google Cloud Auth Manager ভল্টের মধ্যে ব্যবহারকারীর ক্রেডেনশিয়াল নিরাপদে ম্যানেজ করলেও, এটি নিজে থেকে OAuth টোকেন এক্সচেঞ্জ সম্পূর্ণ করতে পারে না। ৩LO হ্যান্ডশেক ক্লায়েন্ট অ্যাপ্লিকেশনকে নির্ভর করে, যাতে এই ফাঁক পূরণ করা যায়:
- কোনও ব্যবহারকারী GitHub অ্যাপকে অনুমোদন দিলে, GitHub তাকে এজেন্ট আইডেন্টিটি অথেন্টিকেশন প্রদানকারীর
redirectUrl-এ রিডাইরেক্ট করে। - তারপরে, Auth Manager ব্যবহারকারীর ব্রাউজারের পপ-আপকে ক্লায়েন্ট-সাইড কলব্যাক URL-এ (
continue_uri) রিডাইরেক্ট করে। - এই রিডাইরেক্ট ইন্টারসেপ্ট করা, ব্রাউজারের কুকি থেকে ননস পড়া এবং হ্যান্ডশেক সম্পূর্ণ করতে Google Cloud-এর
credentials:finalizeএন্ডপয়েন্ট কল করা ক্লায়েন্ট অ্যাপ্লিকেশনের দায়িত্ব। - ক্লায়েন্ট এক্সচেঞ্জ চূড়ান্ত করলে, Google Cloud নিরাপদে টোকেনটি অথেন্টিকেশন প্রদানকারীর ভল্টে সেভ করে, এর ফলে এজেন্ট GitHub টুল কল করতে পারে।
এই কাস্টম ক্লায়েন্ট কলব্যাক এন্ডপয়েন্ট হোস্ট না করলে, হ্যান্ডশেক অসম্পূর্ণ থেকে যায় এবং ভল্ট ক্রেডেনশিয়াল সেভ করতে পারে না।
ইন্ট্যার্যাক্টিভ OAuth 3LO ফ্লো একাধিক লেয়ার জুড়ে বিস্তৃত। টুল অনুরোধের সম্পূর্ণ এক্সিকিউশন লাইফসাইকেল এখানে দেওয়া হল। নিচে দেওয়া ব্যাখ্যা ও পরবর্তী ধাপে আমরা এটি বিস্তারিতভাবে জানাব।
👉 ছবিটি বড় করে দেখতে সেটিতে ক্লিক করুন।
হ্যান্ডশেকে ক্লায়েন্টের মূল দায়িত্ব
- সম্মতি সংক্রান্ত চ্যালেঞ্জ রিলে করা (ধাপ ৫-৬): এজেন্ট একটি
adk_request_credentialপাঠায় যাতে সম্মতি URL ও একবার ব্যবহারযোগ্য ননস থাকে; ক্লায়েন্ট পপ-আপ খোলে এবং ননসকে কুকি হিসেবে সেভ করে। - রিডাইরেক্ট কলব্যাক হোস্ট করুন (ধাপ ১০-১১):
/validateUserId, যেখানে সম্মতি পাওয়ার পরে Auth Manager পপ-আপ পাঠায়। - টোকেন চূড়ান্ত করা (ধাপ ১২-১৪): ক্যাশে করা ননসের সাথে রিডাইরেক্ট থেকে যাচাইকরণ স্টেট একত্রিত করুন এবং
credentials:finalizeকল করুন, যা ভল্টে টোকেন সেভ করে।
আপনার নিজস্ব ক্লায়েন্ট তৈরি করা
ল্যাবের জন্য আপনাকে এই ক্লায়েন্টকে লিখতে হবে না — পরবর্তী ধাপে আগে থেকে তৈরি করা একটি রান করা হবে। আপনার নিজের অ্যাপ্লিকেশনে এটি প্রয়োগ করার সময়, এই দুটি রেফারেন্স থেকে কাজ করতে হবে:
- Auth Manager ডকুমেন্টেশনে আপনার ক্লায়েন্ট-সাইড অ্যাপ্লিকেশন আপডেট করুন, এতে সম্মতি সংক্রান্ত চ্যালেঞ্জ ম্যানেজ করা এবং
credentials:finalizeকল করা অন্তর্ভুক্ত। - adk-python রিপোজিটরিতে রান করা যায় এমন স্যাম্পেল ক্লায়েন্ট। উপরের তিনটি দায়িত্বের সম্পূর্ণ, কার্যকরী প্রয়োগের জন্য
main.pyপড়ুন।
৮. UI ক্লায়েন্ট লোকালি রান করানো
3LO সম্মতি ফ্লো সিকোয়েন্স ডায়াগ্রামে আমরা যেমন ট্রেস করেছি, Auth Manager-কে ব্রাউজার পপ-আপকে ক্লায়েন্ট-সাইড কলব্যাক এন্ডপয়েন্টে রিডাইরেক্ট করতে হবে। নমুনা ক্লায়েন্ট /validateUserId-এ সেই এন্ডপয়েন্ট হোস্ট করে। এটি লোকালি চালানো যাক।
লোকাল ফোল্ডারে ক্লায়েন্ট ফাইল কপি করা
adk-python GitHub রিপোজিটরি-তে gcp_auth/client ফোল্ডারে নেভিগেট করুন। আমাদের চ্যাট ক্লায়েন্ট কন্টেনার তৈরি করার জন্য প্রয়োজনীয় অ্যাসেট এই ফোল্ডারে থাকে।
👉 gcp_auth/client-এর অধীনে থাকা সব ফাইল আপনার লোকাল এনভায়রনমেন্টে কপি করুন:
main.py: টোকেন ফাইনাল করার কলব্যাক (/validateUserId) সহ FastAPI অ্যাপ্লিকেশন স্ক্রিপ্ট যা আমরা আগের বিভাগে আলোচনা করেছি।static/: HTML পৃষ্ঠা থাকে।
বিকল্প হিসেবে, আপনি ফোল্ডারের স্পার্স চেক-আউটও করতে পারেন:
git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
cd adk-python
git sparse-checkout init --cone
git sparse-checkout set contributing/samples/integrations/gcp_auth/client
git checkout
ক্লায়েন্ট চালান
- আপনি যে
clientফোল্ডারটি কপি করেছেন সেখানে নেভিগেট করুন:cd adk-python/contributing/samples/integrations/gcp_auth/client - ভার্চুয়াল এনভায়রনমেন্ট তৈরি করুন এবং ক্লায়েন্টের ডিপেন্ডেন্সি ইনস্টল করুন। ফোল্ডারে একটি
requirements.txtআছে কিন্তু কোনওpyproject.tomlনেই, তাইuv run uvicorn ...নিজে থেকেইFailed to spawn: uvicornমেসেজ দেখিয়ে ব্যর্থ হয়:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - আপনি যে এজেন্ট ডেপ্লয় করেছেন সেটির দিকে ক্লায়েন্টকে পয়েন্ট করুন, তারপর পোর্ট
8501-এ এটি চালু করুন:export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID export GOOGLE_CLOUD_LOCATION=us-central1 export AGENT_ID=YOUR_ENGINE_ID .venv/bin/uvicorn main:app --port 8501 - সার্ভার ঠিকভাবে চালু হয়েছে কিনা এবং
http://localhost:8501-এ শুনছে কিনা তা যাচাই করুন।
৯. OAuth ফ্লো পরীক্ষা করা
এখন যেহেতু সব পরিষেবা ডিপ্লয় করা হয়েছে, IAM বাইন্ডিং কনফিগার করা হয়েছে এবং এনভায়রনমেন্ট ভেরিয়েবল সেট করা হয়েছে, তাই আপনি সুরক্ষিত এন্ড-টু-এন্ড ব্যবহারকারী-প্রতিনিয়োজিত অনুমোদন ফ্লো পরীক্ষা করার জন্য প্রস্তুত!
ধাপ ক: টুল এক্সিকিউশন শুরু করা
- ব্রাউজার ট্যাব খুলুন এবং আপনার ক্লায়েন্ট URL-এ নেভিগেট করুন:
http://localhost:8501. - বাঁদিকের প্যানে, এজেন্টের ধরন
Remote Agent Engineহিসেবে সেট করুন। - আপনার Google Cloud প্রোজেক্ট ও লোকেশন টাইপ করুন।
Load Remote Agents-এ ক্লিক করুন। এর ফলে আপনার প্রোজেক্টে ডিপ্লয় করা সব এজেন্ট লোড হয়ে যাবে। - ড্রপডাউন থেকে সঠিক এজেন্ট বেছে নিয়ে সেটিংস সেভ করুন।
- চ্যাট বক্সে, এগুলি টাইপ করুন:
Fetch my contributions across my private repositories over the last 6 months - চ্যাট UI লক্ষ্য করুন: যেহেতু এজেন্টের কাছে এখনও আপনার ব্যবহারকারীর সেশনের কোনও ক্রেডেনশিয়াল নেই, তাই এটি একটি যাচাইকরণ সংক্রান্ত চ্যালেঞ্জ পায় এবং কথোপকথনের থ্রেডে 'যাচাইকরণ প্রয়োজন' কার্ড দেখায়।
ধাপ খ: ৩-লেগড OAuth সম্মতি সম্পূর্ণ করুন
- একটি আলাদা ব্রাউজার পপ-আপ উইন্ডো খুলবে, যা আপনাকে Google Cloud-এর Auth Manager-এর মাধ্যমে GitHub OAuth অনুমোদন পৃষ্ঠায় রিডাইরেক্ট করবে।
- অনুরোধ করা অনুমতি পর্যালোচনা করে অনুমতি দিন বিকল্পে ক্লিক করুন।
- GitHub, Google Cloud-এ রিডাইরেক্ট করবে, যা পপ-আপকে আপনার
localhostকলব্যাক URL/validateUserId-এ রিডাইরেক্ট করে। - কলব্যাক পরিষেবা ক্রেডেনশিয়াল হ্যান্ডশেক প্রসেস করে এবং চূড়ান্ত করে।
ধাপ গ: আবার চালু করা
- পপ-আপ উইন্ডো বন্ধ হয়ে গেলে, 'অভিভাবকীয় চ্যাট' ট্যাব অটোমেটিক বন্ধ হয়ে যাওয়ার বিষয়টি শনাক্ত করে।
- ফ্রন্টএন্ড, এজেন্টকে আবার একটি রিজুম পেলোড পাঠায়।
- Google Cloud Auth Manager থেকে এজেন্ট নিরাপদে নতুন করে এক্সচেঞ্জ করা টোকেন রিট্রিভ করে, আপনার হয়ে GitHub MCP টুল কল করে এবং আপনার ব্যক্তিগত রিপোজিটরি থেকে সরাসরি চ্যাট উইন্ডোতে ডেটা স্ট্রিম করে — এজেন্ট নিজে থেকে এই ডেটা অ্যাক্সেস করতে পারত না।
ধাপ ঘ: Cloud লগ পরীক্ষা করা
টোকেন এক্সচেঞ্জ ও ফাইনাল প্রসেস নিরাপদে প্রসেস করা হয়েছে কিনা তা যাচাই করতে:
- Google Cloud Console-এর Logs Explorer-এ যান।
- নন্স এক্সট্র্যাক্ট করা ও সফলভাবে যাচাই করা হয়েছে তা কনফার্ম করা সার্ভার লগ খুঁজে দেখুন:
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - এজেন্ট রানটাইম লগ চেক করা: বিকল্প হিসেবে, আপনি সরাসরি এজেন্ট প্ল্যাটফর্ম কনসোলের মধ্যে এক্সিকিউশন লগ দেখতে পারেন:
- এজেন্ট রানটাইম কনসোলে নেভিগেট করুন।
- তালিকা থেকে আপনার ডেপ্লয় করা এজেন্টে ক্লিক করুন।
- প্লেগ্রাউন্ড ট্যাবে যান; এটি নিচের প্যানেলে লাইভ এজেন্ট লগ দেখাবে, যা আপনাকে এজেন্টের রিজনিং লুপ, টুল এক্সিকিউশনের বিবরণ এবং রিয়েল-টাইমে টোকেন রিট্রিভালের লাইফসাইকেল দেখাবে।
১০. ক্লিন-আপ করা
Google Cloud-এ চার্জ এড়াতে, আপনার ডেপ্লয় করা রিসোর্স পরিষ্কার করুন:
# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3
# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
--project=YOUR_PROJECT_ID --location=us-central1
# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.
# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID
# Optionally, delete the GitHub PAT Token and the OAuth app:
# https://github.com/settings/personal-access-tokens
লোকাল ফাইল ক্লিন-আপ করা
বিকল্প হিসেবে, আপনার লোকাল এনভায়রনমেন্ট সম্পূর্ণভাবে ক্লিন-আপ করতে:
- যে টার্মিনালে লোকাল uvicorn সার্ভার চলছে সেখানে Ctrl+C টিপে সেটি বন্ধ করুন।
- এই ল্যাব চলাকালীন তৈরি করা প্রোজেক্ট ডিরেক্টরি সরিয়ে দিন:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
১১. অভিনন্দন!
আপনি সাইন-ইন করা ব্যবহারকারীর হয়ে কাজ করে এমন একটি এজেন্ট সফলভাবে তৈরি ও সুরক্ষিত করেছেন!
আপনি যা শিখেছেন:
- এজেন্ট সিস্টেম আইডেন্টিটি: GCP ইনফ্রাস্ট্রাকচারের সাথে নিরাপদে ইন্টারফেস করা, টেলিমেট্রি লগ ম্যানেজ করা এবং ক্রেডেনশিয়াল ফাইনাল করার API কল করার জন্য এজেন্ট কীভাবে তার নিজস্ব অ্যাকাউন্ট আইডেন্টিটির অধীনে কাজ করে।
- ব্যবহারকারীর হয়ে কাজ করার জন্য এজেন্টকে দেওয়া পরিচয়: ৩-লেগড OAuth (3LO) সম্মতি ফ্লো ট্রিগার করার মাধ্যমে কীভাবে এজেন্ট এক্সটার্নাল প্ল্যাটফর্মে (যেমন, GitHub) ব্যবহারকারীর হয়ে কাজ করার জন্য অনুমোদনের অনুরোধ জানায়।
- নিরাপদ টুল ইন্টিগ্রেশন: হার্ডকোড করা সিক্রেট ব্যবহার না করে, কীভাবে Google Cloud Auth Manager ব্যবহার করে ADK এজেন্টদের মডেল কন্টেক্সট প্রোটোকল (MCP) সার্ভারের সাথে ডায়নামিক উপায়ে ব্যবহারকারীর টোকেন ফেচ করার জন্য কানেক্ট করতে হয়।
- IAM নীতি কনফিগারেশন: কীভাবে এজেন্ট রানটাইম পরিচয় ও আপনার নিজের অ্যাকাউন্ট, দু'টিকেই অনুমোদন প্রদানকারীর কাছে অনুমোদন করার জন্য ফাইন-গ্রেনড অনুমতি বাইন্ডিং সেট-আপ করতে হয়।
আরও পড়ুন
- যাচাইকরণ ফ্লো কনফিগারেশন ও স্কোপ বুঝতে এজেন্ট আইডেন্টিটি যাচাইকরণ ম্যানেজার।
- এজেন্ট রানটাইম ওভারভিউ
- ADK ডকুমেন্টেশন
- মডেল কন্টেক্সট প্রোটোকল