1. ภาพรวม
ใน Codelab นี้ คุณจะได้เรียนรู้วิธีใช้ Agents CLI เพื่อควบคุมวงจรการพัฒนา AI Agent ในเครื่องทั้งหมด ไม่ว่าคุณจะใช้โมเดล Gemini ที่มีอยู่หรือสร้าง Agent ที่กำหนดเองตั้งแต่เริ่มต้นด้วย Agent Development Kit (ADK 2.0) Agents CLI ก็มีเครื่องมือในการสร้างโครงสร้างพื้นฐาน สร้าง ตรวจสอบโค้ด และทดสอบ Agent ในเครื่อง
สิ่งที่คุณจะได้เรียนรู้
- วิธีติดตั้งและตั้งค่า
agents-cliและทักษะที่เกี่ยวข้อง - วิธีสร้างโครงสร้างพื้นฐานของโปรเจ็กต์ Agent ใหม่
- โครงสร้างและไฟล์สำคัญของโปรเจ็กต์ Agent เวิร์กโฟลว์กราฟ ADK 2.0
- วิธีเรียกใช้การตรวจสอบโค้ดอัตโนมัติและการล้างโค้ด
- วิธีเปิดและใช้เว็บเพลย์กราวด์ในเครื่องเพื่อการทดสอบแบบอินเทอร์แอกทีฟด้วยการโหลดซ้ำอัตโนมัติ
สิ่งที่ต้องมี
- Python 3.11 ขึ้นไป
- uv
- Node.js 18 ขึ้นไป (หากใช้ทักษะ Agent ในการเขียนโค้ด)
- Antigravity IDE (ติดตั้งและกำหนดค่าจาก Google Antigravity)
ข้อกำหนดเบื้องต้น
Codelab นี้ถือว่าคุณคุ้นเคยกับสิ่งต่อไปนี้
- การใช้เทอร์มินัลและบรรทัดคำสั่ง
ไม่จำเป็นต้องมีประสบการณ์เกี่ยวกับ AI Agent หรือ ADK 2.0 มาก่อน
2. ตั้งค่าการตรวจสอบสิทธิ์และสภาพแวดล้อม
ระบุข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์เพื่อให้ Agent เรียกใช้โมเดล Gemini ได้
ตัวเลือกที่ 1: คีย์ Gemini API (Google AI Studio)
หากใช้คีย์ Gemini API มาตรฐาน (ซึ่งรับได้จาก Google AI Studio) ให้ส่งออกคีย์ดังกล่าวในเซสชันเทอร์มินัล IDE
export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE
ตัวเลือกที่ 2: ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน Google Cloud
หากใช้ Vertex AI ใน Google Cloud ให้ตรวจสอบสิทธิ์ด้วยข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน Google Cloud (ADC) และตั้งค่าโปรเจ็กต์ Google Cloud ที่ใช้งานอยู่
gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location
3. ตั้งค่า Agents CLI และทักษะ
ขั้นตอนแรกคือการติดตั้งเครื่องมือ agents-cli เครื่องมือนี้จะจัดการงานที่ซับซ้อนในการจัดการโปรเจ็กต์ Agent
เมื่อติดตั้ง Antigravity แล้ว ให้เรียกใช้คำสั่งการตั้งค่าในเทอร์มินัลโดยตรง
👉 เปิดเทอร์มินัลแล้วเรียกใช้คำสั่งต่อไปนี้
uvx google-agents-cli setup
คำสั่งนี้จะติดตั้งสิ่งต่อไปนี้โดยอัตโนมัติ
- เครื่องมือ Agents CLI ทั่วโลกในระบบ
- ทักษะ ผู้ช่วยเขียนโค้ดเฉพาะโดเมน 7 รายการที่ Antigravity ใช้เพื่อช่วยคุณสร้างโครงสร้างพื้นฐาน ประเมิน และติดตั้งใช้งาน Agent ระบบจะติดตั้งทักษะเหล่านี้เพียงครั้งเดียวทั่วโลกใน
~/.agents/skills/และ Antigravity จะค้นพบทักษะเหล่านี้โดยอัตโนมัติ
หมายเหตุ: ระบบจะติดตั้งทักษะใน ~/.agents/skills/ และ Antigravity จะเลือกทักษะเหล่านี้โดยอัตโนมัติ คุณสามารถยืนยันได้โดยใช้คำสั่ง /skills หรือการตั้งค่า Antigravity
ผลลัพธ์ที่คาดไว้ (ตัดทอน)
█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`
`Your coding agent just got an upgrade.`
`1. Authentication`
`─────────────────`
`✓ Authenticated with Google Cloud`
`2. CLI Installation`
`───────────────────`
`▸ uv tool install google-agents-cli`
`✓ Installed google-agents-cli`
`3. Skills Installation`
`──────────────────────`
`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`
`◇ Found 7 skills`
`~/.agents/skills/google-agents-cli-adk-code`
`~/.agents/skills/google-agents-cli-deploy`
`~/.agents/skills/google-agents-cli-eval`
`~/.agents/skills/google-agents-cli-observability`
`~/.agents/skills/google-agents-cli-publish`
`~/.agents/skills/google-agents-cli-scaffold`
`~/.agents/skills/google-agents-cli-workflow`
4. สร้างโปรเจ็กต์ Agent
ในส่วนนี้ คุณจะได้สร้างไดเรกทอรีโปรเจ็กต์ที่มีโครงสร้างครบถ้วนโดยใช้เทมเพลตต้นแบบ
👉 แจ้ง Antigravity ดังนี้
Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.
Antigravity จะเรียกใช้คำสั่งการสร้างโครงสร้างพื้นฐาน (agents-cli scaffold create customer-support-agent --prototype --yes) โดยอัตโนมัติและตั้งค่าไฟล์โปรเจ็กต์ให้คุณ
5. สำรวจโค้ด Agent
👉 ขอให้ Antigravity อธิบายโค้ดที่สร้างขึ้น
Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.
ใน Antigravity IDE ระบบจะแสดงไฟล์และอาร์ติแฟกต์โปรเจ็กต์ที่สร้างขึ้นใหม่ในบานหน้าต่างเสริม (ด้านซ้าย) โดยตรง คุณสามารถดู app/agent.py ในบานหน้าต่างดังกล่าว หรือเปิดจากโปรแกรมสำรวจไฟล์ IDE เพื่อสำรวจโค้ดที่สร้างโครงสร้างพื้นฐานไว้
# app/agent.py
from __future__ import annotations
from typing import Any, Literal
from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field
class InquiryCategory(BaseModel):
category: Literal['shipping', 'unrelated'] = Field(
description=(
'Determine if the user query is related to shipping (rates, tracking,'
' delivery times, returns) or unrelated.'
)
)
def save_query(node_input: str):
"""Saves user query in state for downstream nodes."""
yield Event(data=node_input, state={'user_query': node_input})
categorize_agent = LlmAgent(
name='categorize',
model='gemini-3.1-flash-lite',
instruction='You are an expert classifier. Categorize the user query.',
output_key='inquiry_category',
output_schema=InquiryCategory,
)
@node
def route_inquiry(ctx: Context, node_input: Any):
"""Routes the workflow based on the classified category."""
category_data = ctx.state.get('inquiry_category', {})
category = category_data.get('category', 'unrelated')
query = ctx.state.get('user_query', '')
yield Event(data=query, route=category)
faq_agent = LlmAgent(
name='shipping_faq',
model='gemini-3.1-flash-lite'',
instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
SHIPPING FAQ:
- Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
over $50 qualify for free standard shipping.
- Tracking: You can track your order by entering your tracking number on
our website's tracking page.
- Delivery Times: Standard delivery takes 3-5 business days. Express
delivery takes 1-2 business days.
- Returns: We offer free returns within 30 days of delivery. Please make
sure the item is in its original condition.
""",
)
@node
def handle_unrelated(ctx: Context, node_input: Any):
"""Handles unrelated inquiries politely."""
yield Event(
data=(
'I am sorry, I am a shipping customer support assistant and can only'
' answer questions related to our shipping FAQ.'
)
)
root_agent = Workflow(
name='customer_support_workflow',
edges=[
*Edge.chain('START', save_query, categorize_agent, route_inquiry),
(route_inquiry, faq_agent, 'shipping'),
(route_inquiry, handle_unrelated, 'unrelated'),
],
)
app = App(
name='customer_support_agent',
root_agent=root_agent,
)
หัวข้อสำคัญ
- เวิร์กโฟลว์และ Edge: ใน ADK 2.0 ระบบจะจัดระเบียบแอปพลิเคชัน Agent เป็นกราฟโดยใช้
Workflowรายการedgesจะกำหนดโฟลว์การดำเนินการ โดยเชื่อมโยงโหนดต่างๆ เข้าด้วยกันจากSTARTและเปิดใช้การแยกสาขาแบบมีเงื่อนไขตามเส้นทาง (เช่น การกำหนดเส้นทางไปยังfaq_agentใน"shipping"หรือhandle_unrelatedใน"unrelated") - LlmAgent: โหนดประกาศที่กำหนดงานที่ขับเคลื่อนด้วย LLM พร้อมคำแนะนำ โมเดล และเอาต์พุตที่มีโครงสร้าง (
output_schema) ที่เฉพาะเจาะจง - โหนดและบริบท: ฟังก์ชัน Python ที่ตกแต่งด้วย
@node(หรือฟังก์ชันมาตรฐาน) ซึ่งดำเนินการตรรกะ เข้าถึงสถานะการดำเนินการผ่านContextและสร้างออบเจ็กต์Eventเพื่อส่งข้อมูลและสัญญาณการกำหนดเส้นทางไปตามกราฟ - โมเดล: ระบบจะใช้ `gemini-3.1-flash-lite' เป็นโมเดลการให้เหตุผลที่รวดเร็วเริ่มต้น
- App Wrapper: ออบเจ็กต์ระดับบนสุด
Appจะรวมเวิร์กโฟลว์ราก เครื่องมือภายนอก เช่น เพลย์กราวด์ในเครื่อง ชุดเครื่องมือประเมิน ADK และ Agent Runtime จะค้นพบและเรียกใช้เวิร์กโฟลว์ของคุณผ่านอินเทอร์เฟซappที่ได้มาตรฐานนี้
6. การตรวจสอบโค้ดอัตโนมัติ
ก่อนที่จะเรียกใช้หรือทดสอบ Agent คุณควรตรวจสอบว่าโค้ดสะอาดและจัดรูปแบบอย่างถูกต้อง
👉 แจ้ง Antigravity ดังนี้
Run linting on my agent project to verify its health.
Antigravity จะเรียกใช้ agents-cli lint เบื้องหลังเพื่อเรียกใช้การตรวจสอบที่กำหนดค่าไว้ล่วงหน้า โดยจะตรวจสอบการนำเข้า ไวยากรณ์ และความสอดคล้องของการจัดรูปแบบในไฟล์
7. การทดสอบแบบอินเทอร์แอกทีฟด้วยเพลย์กราวด์
เว็บเพลย์กราวด์ในเครื่องเป็นวิธีที่เร็วที่สุดในการยืนยันลักษณะการทำงานของ Agent โดยมีอินเทอร์เฟซแชทแบบอินเทอร์แอกทีฟที่คุณสามารถแชทกับ Agent และตรวจสอบการดำเนินการเครื่องมือแบบเรียลไทม์ได้
👉 แจ้ง Antigravity ดังนี้
Launch the local development playground for my agent.
Antigravity จะเริ่มเซิร์ฟเวอร์การพัฒนาในเครื่อง (agents-cli playground) เปิด URL ที่ระบุ (โดยปกติคือ http://127.0.0.1:8080/dev-ui/?app=app) ในเว็บเบราว์เซอร์ เลือกโฟลเดอร์ app จากเมนูแบบเลื่อนลงเพื่อเริ่มแชทกับ Agent
เริ่มแชทกับ Agent ในอินเทอร์เฟซเว็บ ลองถามคำถามเกี่ยวกับการจัดส่ง
How much is standard shipping?
สังเกตว่าเวิร์กโฟลว์จัดหมวดหมู่และกำหนดเส้นทางไปยัง faq_agent เพื่อตอบคำถามได้สำเร็จ นอกจากนี้ ให้ลองถามคำถามที่ไม่เกี่ยวข้องเพื่อยืนยันว่าเวิร์กโฟลว์กำหนดเส้นทางไปยัง handle_unrelated และปฏิเสธที่จะตอบคำถามอย่างถูกต้อง
What is the weather like?
ทดสอบการโหลดซ้ำอัตโนมัติแบบเรียลไทม์
คุณจะเห็นว่าการแก้ไข Agent แบบเรียลไทม์แสดงในเพลย์กราวด์อย่างไร
- แก้ไขคำแนะนำ
faq_agentในapp/agent.pyโดยขอให้ Antigravity ทำดังนี้Modify the faq_agent instruction in app/agent.py to make the shipping rates response more playful and enthusiastic. Add some emojis and highlight the free shipping threshold. - ส่งข้อความใหม่ไปยัง Agent ในเพลย์กราวด์เพื่อทดสอบการโหลดซ้ำอัตโนมัติ
How much is standard shipping?
8. การดำเนินการบรรทัดคำสั่ง
สำหรับการทดสอบอย่างรวดเร็ว การทำงานอัตโนมัติ หรือการเขียนสคริปต์ คุณสามารถขอให้ Antigravity เรียกใช้ Agent จากเทอร์มินัลโดยตรง
👉 แจ้ง Antigravity ดังนี้
Run a CLI query asking my agent how long standard delivery takes.
Antigravity จะเรียกใช้คำสั่งการค้นหา (agents-cli run "How long does standard delivery take?") ซึ่งจะเรียกใช้การอนุมานแบบครั้งเดียวอย่างรวดเร็วและพิมพ์การตอบกลับสุดท้ายของ Agent พร้อมรายละเอียดการดำเนินการเครื่องมือ
9. การทำความสะอาดข้อมูล
ทำตามขั้นตอนการล้างข้อมูลต่อไปนี้เพื่อหลีกเลี่ยงการทิ้งทรัพยากรที่ไม่ต้องการไว้ในสภาพแวดล้อมในเครื่อง
- หยุดเซิร์ฟเวอร์ในเครื่อง: หากเซิร์ฟเวอร์
agents-cli playgroundยังคงทำงานอยู่ ให้หยุดเซิร์ฟเวอร์ในเทอร์มินัลโดยกดCtrl + C - นำไฟล์โปรเจ็กต์ในเครื่องออก: ลบไดเรกทอรีโปรเจ็กต์ Agent ที่สร้างโครงสร้างพื้นฐานไว้จากเครื่องในเครื่อง
rm -rf customer-support-agent
10. สรุปและขั้นตอนถัดไป
ยินดีด้วย คุณจัดการวงจรการพัฒนา AI Agent ในเครื่องแบบครบวงจรได้สำเร็จโดยใช้ Agents CLI และ ADK 2.0
สิ่งที่คุณได้เรียนรู้
- ตั้งค่าเครื่องมือ: ติดตั้ง Agents CLI และกำหนดค่าทักษะเวิร์กโฟลว์เฉพาะโดเมนสำหรับ Antigravity
- สร้างโครงสร้างพื้นฐานของโปรเจ็กต์: สร้างโปรเจ็กต์ที่มีโครงสร้างครบถ้วนโดยใช้เทมเพลตที่ได้มาตรฐาน
customer-support-agent - วิเคราะห์โครงสร้าง ADK 2.0: สำรวจเวิร์กโฟลว์กราฟ, LLM Agent, โหนด, Edge และการกำหนดเส้นทางแบบมีเงื่อนไข
- จัดการความสมบูรณ์ในเครื่อง: เรียกใช้การตรวจสอบคุณภาพโค้ดอัตโนมัติโดยใช้
agents-cli lint - ยืนยันลักษณะการทำงาน: ทดสอบ Agent แบบอินเทอร์แอกทีฟด้วยการโหลดซ้ำแบบเรียลไทม์ผ่านเพลย์กราวด์ และเรียกใช้การทดสอบอย่างรวดเร็วในบรรทัดคำสั่ง
ขั้นตอนต่อไปคือ
ตอนนี้คุณเชี่ยวชาญวงจรการพัฒนาในเครื่องแล้ว ต่อไปนี้คือวิธีขยายและนำ Agent ไปใช้จริง
- การประเมิน: ให้คะแนน Agent กับชุดข้อมูลการประเมินโดยใช้
agents-cli eval runเพื่อวัดความถูกต้องและค้นหาการถดถอย - การปรับขนาดระบบคลาวด์ระดับองค์กร: การทำให้ใช้งานได้ & ความสามารถในการสังเกต: แพ็กเกจและทำให้ใช้งานได้ Agent ในสภาพแวดล้อมฮาร์ดแวร์และซอฟต์แวร์ เช่น Agent Runtime หรือ Cloud Run โดยใช้
agents-cli deployตั้งค่าการวัดและส่งข้อมูลระยะไกลของการใช้งานจริงเพื่อสตรีมบันทึกและการติดตามการดำเนินการไปยัง Cloud Trace และ BigQuery