Tạo một tác nhân bản tin công nghệ được quản lý bằng Gemini API

1. Tổng quan

Bối cảnh AI và công nghệ thay đổi nhanh hơn bất kỳ ai có thể theo dõi. Các mô hình, bài viết và sản phẩm mới được ra mắt hằng ngày. Một tác nhân tóm tắt có thể tìm nạp tiêu đề hôm nay, viết bản tóm tắt ngắn gọn và tạo một tệp PDF mỗi buổi sáng sẽ giải quyết vấn đề đó. Tuy nhiên, việc tạo một tác nhân như vậy thường có nghĩa là bạn phải chọn một khung, xác định các công cụ trong Python, viết một vòng lặp điều phối, đóng gói một vùng chứa và triển khai đến Cloud Run. Tất cả những điều đó đều diễn ra trước khi tác nhân thực hiện một yêu cầu web duy nhất.

Các tác nhân được quản lý trên API Gemini sẽ thay đổi phương trình này. Bạn viết 2 tệp cấu hình markdown và một tập lệnh trình kết xuất được tạo sẵn, thực hiện một lệnh gọi API và một hộp cát Ubuntu thực sẽ khởi động, duyệt web, viết bản tóm tắt và tạo một tệp PDF. Không có vùng chứa. Không có quy trình triển khai. Không có mã điều phối.

Trong lớp học lập trình này, bạn sẽ xây dựng chính xác tác nhân đó: từ một hàm trống đến một bản tóm tắt hằng ngày hoạt động, mỗi lần một khái niệm.

Sản phẩm bạn sẽ tạo ra

  • Tạo và chạy tác nhân được quản lý đầu tiên trong một hộp cát Linux thực
  • Tuỳ chỉnh tác nhân bằng hướng dẫn chi tiết
  • Tải tệp PDF đầu ra của tác nhân xuống
  • Tiếp tục cuộc trò chuyện để tinh chỉnh thông tin tóm tắt mà không cần tìm nạp lại thông tin trên web
  • Lưu cấu hình tác nhân và gọi cấu hình đó theo mã nhận dạng trong các lần chạy sau

Bạn cần có

  • Python 3.10 trở lên
  • Khoá Gemini API có bật tính năng thanh toán: aistudio.google.com/api-keys
  • Khoảng 1 đô la tín dụng API (mỗi lần chạy đầy đủ có chi phí từ 0,3 đến 1,3 đô la)

2. Tác nhân được quản lý trên Gemini API là gì?

3 cấp độ của hệ thống AI

Trước khi đi sâu vào mã, đây là vị trí mà Tác nhân được quản lý phù hợp so với 2 lựa chọn thay thế:

Cấp độ

AdWords Express là gì

Ai quản lý cơ sở hạ tầng?

Mô hình ngôn ngữ lớn (LLM) tiêu chuẩn

Bạn đưa ra câu lệnh, Gemini sẽ trả lời bằng văn bản. Không cần dùng tay, không cần bộ nhớ, không cần Internet.

Không áp dụng: không thể tự làm gì

Tác nhân tự lưu trữ

Bạn kết nối ADK/LangChain/AutoGen + Docker + các công cụ + bộ nhớ.

Bạn: tất cả (hoặc một nền tảng được quản lý như Agent Engine)

Tác nhân được quản lý

Bạn đặt mục tiêu cho nó. Google cung cấp một hộp cát bảo mật. Tác nhân tự động viết mã, chạy mã, đọc lỗi, tìm kiếm trên web và sửa lỗi.

Google: tất cả

Lớp học lập trình này nói về hàng thứ ba. Bạn cung cấp một tệp cấu hình và tệp nhiệm vụ. Google sẽ xử lý mọi việc khác.

Những gì bạn sẽ tạo bằng ADK + Cloud Run

Để tạo một tác nhân tóm tắt tin tức duyệt web, chạy Python và tạo một tệp PDF, bạn sẽ cần tất cả những điều này với ADK + Cloud Run:

# agent.py: define tools and wire up the agent
from google.adk.agents import LlmAgent
from google.adk.tools import google_search, built_in_code_execution

agent = LlmAgent(
    name="digest-agent",
    model=MODEL,
    instruction=AGENTS_MD,          # your editorial voice and rules
    tools=[google_search, built_in_code_execution],
)

# app.py: serve the agent over HTTP
from google.adk.runners import FastApiRunner
runner = FastApiRunner(agent=agent)
app = runner.app

# pdf_tool.py: custom tool, install reportlab, render PDF
# scraper.py: custom tool, fetch each news source
# streaming.py: wire agent events to your SSE endpoint

# Dockerfile: package everything
FROM python:3.12
COPY . /app
RUN pip install google-adk reportlab requests
CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]

# Deploy to Cloud Run
gcloud run deploy digest-agent \
  --image gcr.io/your-project/digest-agent \
  --set-secrets GEMINI_API_KEY=gemini-key:latest \
  --memory 2Gi

Đó là trước khi tác nhân chạy một lần. Bạn vẫn sở hữu tính năng cách ly hộp cát (vì vậy, tác nhân không thể làm hỏng máy chủ của bạn), quá trình cài đặt gói, quản lý trạng thái giữa các lệnh gọi công cụ và cơ sở hạ tầng truyền trực tuyến để gửi các sự kiện đến một ứng dụng.

Managed Agents thay thế bằng

from google import genai
client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="",
    stream=True,
    environment={
        "type": "remote",
        "sources": [          # your config files, mounted at startup
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

Yêu cầu đối với ADK + Cloud Run

Những việc mà Tác nhân được quản lý sẽ xử lý cho bạn

Hình ảnh vùng chứa + Dockerfile + CI/CD

Hộp cát Ubuntu được quản lý hoàn toàn (Python 3.12, Node 22, 4 CPU / 16 GB RAM)

Triển khai và mở rộng quy mô Cloud Run

Được cung cấp cho mỗi lượt tương tác, tự động hết hạn sau 7 ngày không hoạt động

Cách ly hộp cát

Được cô lập theo mỗi lượt tương tác

Công cụ PDF tuỳ chỉnh + pip install

Tác nhân cài đặt các gói trong hộp cát

Cơ sở hạ tầng phát trực tuyến SSE

stream=True trả về một sự kiện có thể lặp lại

Định nghĩa công cụ bằng Python

Các công cụ tích hợp: duyệt web, thực thi mã, hệ thống tệp

Quản lý trạng thái giữa các lệnh gọi công cụ

Được tích hợp vào vòng lặp suy luận của tác nhân

Bạn viết các tệp cấu hình (AGENTS.md, SKILL.md, một tập lệnh được tạo sẵn) và thực hiện một lệnh gọi API. Google sẽ xử lý mọi việc khác.

Cách hoạt động của hộp cát

interactions.create() call
        │
        ▼
Google provisions Ubuntu sandbox (Python 3.12, Node 22, 4 CPU / 16 GB RAM)
        │
        ▼
Agent reasoning loop:
  plan → fetch URLs → run Python → write files → reason → repeat
        │
        ▼
Events stream back in real time: tool calls, text chunks, completion
        │
        ▼
interaction.completed → environment_id + interaction_id

Hộp cát sẽ duy trì trong 7 ngày không hoạt động. Bạn có thể tiếp tục với environment_id để tinh chỉnh kết quả, chạy các nhiệm vụ tiếp theo hoặc phát triển nhánh kết quả thành một tác nhân đã lưu có tên.

3. Thiết lập

Nhấp vào nút bên dưới để mở lớp học lập trình này trong Google Cloud Shell. Tất cả các phần phụ thuộc đều được cài đặt sẵn.

Mở trong Cloud Shell

Cách B: Thiết lập cục bộ

git clone https://github.com/Saoussen-CH/tech-digest-managed-agent.git
cd tech-digest-managed-agent

Cài đặt uv nếu cần:

curl -LsSf https://astral.sh/uv/install.sh | sh

Định cấu hình khoá API

cp .env.example .env
cloudshell edit .env

Thiết lập khoá:

GEMINI_API_KEY=your-key-here

Cài đặt các phần phụ thuộc

uv sync

4. Thực hiện cuộc gọi đầu tiên bằng tác nhân

Mở tệp khởi đầu

cloudshell edit run_digest.py

run_digest() hiện có một việc cần làm và 3 việc khác cho bước tiếp theo. Hai trợ lý đã được điền sẵn ở phía trên:

  • load_source(path): đọc một tệp từ .agents/ tương ứng với tập lệnh. Bạn sẽ sử dụng công cụ này trong bài tập tiếp theo để gắn tính chất xã luận, cẩm nang PDF và trình kết xuất vào hộp cát.
  • run_stream(stream): xử lý luồng sự kiện và trả về (environment_id, interaction_id). Bạn không cần tự viết vòng lặp sự kiện.

Nội dung cần bổ sung

TODO 1: thay thế pass bằng (tạm thời bỏ qua TODO 3, 4 – những việc này dành cho bước tiếp theo):

    from google import genai
    client = genai.Client()

    stream = client.interactions.create(
        agent=BASE_AGENT,
        input="Fetch the Hacker News front page and list the top 5 stories.",
        stream=True,
        environment="remote",
    )

    environment_id, interaction_id = run_stream(stream)
    print(f"\nDone. environment_id={environment_id}")

Chức năng của từng phần

genai.Client() đọc GEMINI_API_KEY từ môi trường. Mọi thứ khác đều thông qua ứng dụng này.

interactions.create() là cuộc gọi chính. Có 4 tham số giúp chỉ số này hoạt động:

  • agent=BASE_AGENT: chọn tác nhân Antigravity (antigravity-preview-05-2026), một tác nhân được quản lý đa năng dựa trên Gemini 3.5 Flash. Theo mặc định, công cụ này có 3 công cụ tích hợp được bật: code_execution (chạy Bash, Python, Node.js), google_search và url_context (tìm nạp và đọc các trang web). Các công cụ hệ thống tệp (read_file, write_file, list_files) sẽ tự động bật khi bạn truyền tham số environment. Một lệnh gọi sẽ cung cấp một môi trường Ubuntu được quản lý toàn diện với Python 3.12, Node.js 22, git, pip và curl được cài đặt sẵn. Không cần tạo vùng chứa, không cần chạy quy trình triển khai.
  • input: tác vụ cho lần chạy này. Tác nhân duyệt xem Hacker News và suy luận về kết quả.
  • environment="remote": cung cấp một hộp cát đám mây mới cho hoạt động tương tác này.
  • stream=True: trả về một đối tượng có thể lặp lại của các sự kiện thay vì chặn. Nếu không có tham số này, lệnh gọi sẽ đợi 30 đến 90 giây và trả về tất cả đầu ra cùng một lúc dưới dạng interaction.output_text. Với tính năng truyền trực tuyến, bạn sẽ thấy lý do của tác nhân và hành động ngay khi lý do đó xuất hiện. Truyền phát trực tiếp không phải là một tính năng nâng cao ở đây: đây là chế độ mặc định phù hợp, vì hộp đen 90 giây không cho bạn biết liệu tác nhân có đang hoạt động hay bị kẹt.

Những gì bạn vừa cung cấp: mọi lệnh gọi interactions.create() đều khởi động một hộp cát chuyên dụng:

Thành phần

Thông số kỹ thuật

Hệ điều hành

Môi trường Ubuntu Linux biệt lập

Thời gian chạy được cài đặt sẵn

Python 3.12, Node.js 22, Bash

Điện toán

CPU 4 lõi, RAM 16 GB

Quản lý ngữ cảnh

Tính năng nén tự động sẽ kích hoạt ở khoảng 135.000 mã thông báo

Nối mạng

Quyền truy cập vào web bên ngoài thông qua Egress Proxy

Tác nhân có thể cài đặt mọi gói bằng pip hoặc npm, đọc và ghi tệp, đồng thời thực hiện các yêu cầu web đi ra. Chúng tôi không bao giờ truy cập vào máy và thông tin đăng nhập của bạn.

environment_id là một handle cho hộp cát vừa chạy. Sau interaction.completed, hộp cát sẽ không tắt mà vẫn hoạt động trong tối đa 7 ngày. environment_id là cách bạn quay lại chế độ này. Truyền tham số này đến lệnh gọi interactions.create() thứ hai và tác nhân sẽ tiếp tục trên cùng một hệ thống tệp, với cùng các tệp và gói đã cài đặt, như thể tác nhân chưa từng rời khỏi. Bước tiếp theo sử dụng mã này để tải PDF xuống mà không cần chạy lại tác nhân, còn bước sau đó sử dụng mã này để tiếp tục cuộc trò chuyện.

interaction_id là một giá trị nhận dạng cho lượt trò chuyện vừa hoàn tất. Truyền nó dưới dạng previous_interaction_id trong lệnh gọi tiếp theo và tác nhân sẽ có đầy đủ thông tin về những gì đã nói và làm trong lượt này.

Xác minh

uv run python run_digest.py

Bạn sẽ thấy kết quả trực tiếp khi tác nhân hoạt động:

[agent started]
  [tool] run_code
Here are the top 5 stories currently on the Hacker News front page, retrieved via the official Hacker News API:

1. **Qwen 3.6 27B is the sweet spot for local development** — 471 points
2. **.self: A new top-level domain designed to support self-hosting** — 116 points
...
Done. environment_id=e3de58774073f75a6ef42924c6ce2e88

API này trả về một environment_id thực ngay cả khi có environment="remote". Hộp cát đã chạy. Điều còn thiếu là cấu hình: không có giọng nói, không có kỹ năng, không có trình tạo PDF. Tác nhân chỉ in các câu chuyện dưới dạng văn bản rồi dừng lại. Bước tiếp theo sẽ thêm những điều kiện ràng buộc đó.

Mỗi dòng đầu ra tương ứng với một sự kiện từ run_stream():

step.type

Định nghĩa

Ảnh in run_stream()

"url_context_call"

tác nhân tìm nạp một URL

[tool] url_context (https://...)

"code_execution_call"

tác nhân chạy mã trong hộp cát

[tool] run_code

"google_search_call"

trợ lý tìm kiếm trên web

[tool] google_search

"function_call"

công cụ tệp và các công cụ khác

[tool] read_file (/workspace/...)

step.delta nơi delta.type == "text"

nhân viên hỗ trợ đang viết văn bản

truyền trực tiếp đến stdout

5. Tuỳ chỉnh tác nhân

Trợ lý không có hướng dẫn: không có giọng nói, không có kỹ năng, không có trình tạo PDF. Trong bước này, bạn sẽ tải các tệp cấu hình từ .agents/ và gắn chúng vào hộp cát.

Nội dung cần thay đổi

Thực hiện 4 thay đổi đối với run_digest.py:

CẦN LÀM 2: Bên dưới load_source(), hãy thêm 3 hằng số cấp mô-đun (các hằng số này nằm bên ngoài run_digest(), ở đầu tệp):

AGENTS_MD       = load_source(".agents/AGENTS.md")
SKILL_MD        = load_source(".agents/skills/digest-pdf/SKILL.md")
GENERATE_PDF_PY = load_source(".agents/skills/digest-pdf/scripts/generate_pdf.py")

Mở từng tệp để xem nội dung bạn đang tải: AGENTS.md đặt ra tính chất xã luận và các quy tắc quy trình làm việc; SKILL.md là cẩm nang từng bước dưới dạng PDF; generate_pdf.py là trình kết xuất được tạo sẵn mà tác nhân sẽ chạy.

Bây giờ, hãy thực hiện thêm 2 thay đổi bên trong run_digest():

VIỆC CẦN LÀM 3: thay đổi environment từ "remote" thành từ điển nguồn và đặt input thành "":

        environment={
            "type": "remote",
            "sources": [
                {
                    "type": "inline",
                    "target": ".agents/AGENTS.md",
                    "content": AGENTS_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/SKILL.md",
                    "content": SKILL_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                    "content": GENERATE_PDF_PY,
                },
            ],
        },

TODO 4: thêm các dòng này ngay sau print(f"\nDone. environment_id={environment_id}"):

    set_key(".env", "ENVIRONMENT_ID", environment_id)
    set_key(".env", "INTERACTION_ID", interaction_id)

(set_key đã được nhập ở đầu run_digest.py.)

Thao tác này sẽ ghi cả hai mã nhận dạng vào .env trong lần chạy này, vì vậy, bước tiếp theo có thể tải PDF xuống mà không cần chạy lại tác nhân.

Chức năng của từng nguồn

Mỗi nguồn là một tệp được gắn vào hệ thống tệp hộp cát khi khởi động trước khi tác nhân chạy. Các đường dẫn target khớp với vị trí mà bộ công cụ Antigravity dự kiến sẽ tìm thấy:

.agents/
├── AGENTS.md                              ← auto-loaded as global instructions
└── skills/
    └── digest-pdf/
        ├── SKILL.md                       ← auto-discovered and registered as a skill
        └── scripts/
            └── generate_pdf.py            ← pre-built renderer the agent can run

target đường dẫn

Biến

Tác dụng của dây đai

.agents/AGENTS.md

AGENTS_MD

Tự động tải dưới dạng hướng dẫn cố định: tính chất xã luận, quy trình công việc, quy tắc thực hiện

.agents/skills/digest-pdf/SKILL.md

SKILL_MD

Tự động phát hiện và đăng ký dưới dạng một kỹ năng có tên; tác nhân gọi kỹ năng đó theo tên

.agents/skills/digest-pdf/scripts/generate_pdf.py

GENERATE_PDF_PY

Trình kết xuất PDF được tạo sẵn; tác nhân viết summaries.json rồi chạy tập lệnh này

Xác minh

uv run python run_digest.py

Bây giờ, quá trình chạy mất từ 1 đến 3 phút. Bạn sẽ thấy tác nhân đọc tệp cấu hình, viết bản tóm tắt và lưu tệp PDF:

[agent started]
  [tool] read_file (/.agents/skills/digest-pdf/SKILL.md)
  [tool] list_files (/.agents/skills/digest-pdf/scripts)
  [tool] read_file (/.agents/skills/digest-pdf/scripts/generate_pdf.py)
  [tool] run_code
  [tool] write_file (/workspace/summaries.json)
  [tool] run_code
  [tool] delete_file (/tmp/test_scrape.py)
I have successfully generated today's tech news digest and saved the formatted document to /workspace/digest.pdf.
Done. environment_id=4129ffd75574e308748e9425d7ec828f

environment_id hiện là một giá trị thực: hộp cát chạy với các tệp cấu hình của bạn và tác nhân đã tạo digest.pdf. Bước tiếp theo sẽ tải tệp này xuống.

6. Tải xuống PDF

Tác nhân đã ghi digest.pdf vào /workspace/digest.pdf trong hộp cát. Ảnh chụp nhanh môi trường có sẵn dưới dạng tệp lưu trữ tar thông qua Gemini Files API.

Cài đặt requests nếu cần:

uv pip install requests

Thông tin cần điền

Mở download_pdf.py. Tệp này có 2 việc cần làm.

TODO 1: điền vào lệnh gọi requests.get():

    r = requests.get(
        f"https://generativelanguage.googleapis.com/v1beta/files/environment-{environment_id}:download",
        params={"alt": "media"},
        headers={"x-goog-api-key": api_key},
        allow_redirects=True,
    )
    r.raise_for_status()

URL này đề cập đến thông tin tổng quan nhanh về hộp cát. params={"alt": "media"} trả về các byte thô thay vì siêu dữ liệu. GEMINI_API_KEY hiện có của bạn cũng xác thực Files API.

TODO 2: tìm và trích xuất tệp PDF từ kho lưu trữ tar:

            member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
            tar.extract(member, path=tmp, filter="data")

Tiền tố đường dẫn tar thay đổi theo các lần chạy, vì vậy, hãy tìm kiếm theo hậu tố thay vì mã hoá cứng đường dẫn chính xác. filter="data" sẽ chặn cảnh báo về việc Python 3.13 không dùng nữa tính năng trích xuất tar không an toàn.

Xác minh

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

Mở digest.pdf trong cùng một thư mục. Nội dung này chứa bản tóm tắt được định dạng mà tác nhân tạo ra từ các trang web đang hoạt động.

7. Tiếp tục cuộc trò chuyện

Bạn đã có digest.pdf. Nếu chỉ muốn lấy tệp, bạn đã hoàn tất. Bước này liên quan đến một việc khác: yêu cầu tác nhân thay đổi bản tóm tắt mà không cần tìm nạp lại thông tin trên web.

Hộp cát vẫn hoạt động. Trợ lý vẫn có /workspace/digest.pdf và nhớ mọi câu chuyện mà trợ lý đã tóm tắt. Lệnh gọi interactions.create() thứ hai sẽ gửi một thông báo tiếp theo vào chính hộp cát đó. Ở đây, bạn yêu cầu Gemini thêm một ghi chú "Tại sao điều này lại quan trọng" bên dưới mỗi câu chuyện, đồng thời cập nhật tệp PDF tại chỗ mà không cần tìm nạp lại và tóm tắt lại.

Thông tin cần điền

Mở refine_digest.py. Có 3 việc cần làm.

Việc cần làm 1 và 2: điền vào 2 thông số nhiều lượt trong interactions.create():

    environment=environment_id,
    previous_interaction_id=interaction_id,

environment=environment_id sẽ tiếp tục chạy cùng một hộp cát với các tệp và gói của hộp cát đó. previous_interaction_id=interaction_id cung cấp cho tác nhân nhật ký trò chuyện. Không có gì thay đổi so với lệnh gọi đầu tiên.

TODO 3: duy trì interaction_id mới trở lại .env sau vòng lặp sự kiện:

set_key(".env", "INTERACTION_ID", interaction_id)

Mỗi lệnh gọi interactions.create() sẽ tạo ra một interaction_id mới. Việc ghi lại có nghĩa là lần chạy tiếp theo sẽ truyền thông tin tinh chỉnh này dưới dạng previous_interaction_id, liên kết các lượt một cách chính xác. Mã hộp cát không bao giờ thay đổi nên ENVIRONMENT_ID không cần phải cập nhật.

Hai tham số giúp cuộc trò chuyện nhiều lượt hoạt động

ID

Nội dung được giữ lại

Phép loại suy

environment=environment_id

Tệp, gói đã cài đặt, trạng thái hệ thống: mọi thứ trên hệ thống tệp Linux

Giữ nguyên không gian làm việc giữa các cuộc họp

previous_interaction_id=interaction_id

Nhật ký trò chuyện: những gì tác nhân đã nói và làm trong các lượt trước

Ghi nhớ những nội dung đã thảo luận trong cuộc họp gần nhất

Bạn có thể truyền riêng từng mã nhận dạng:

  • Chỉ trên environment_id: sử dụng lại các tệp và gói, nhưng bắt đầu một cuộc trò chuyện mới. Hữu ích cho một việc cần làm mới trong cùng một không gian làm việc.
  • previous_interaction_id: tiếp tục bối cảnh cuộc trò chuyện, nhưng trong một hộp cát mới (các tệp đã biến mất).
  • Cả hai: tính năng tiếp tục đầy đủ, đây là tính năng mà bước này sử dụng.

Không có environment_id: hộp cát trống, không có tệp PDF. Không có previous_interaction_id: không có ngữ cảnh, nhân viên hỗ trợ không thể tinh chỉnh một phần cụ thể.

Xác minh

uv run python refine_digest.py

Luồng này phải nhanh chóng; tác nhân không tìm nạp lại bất cứ nội dung nào. Sau khi quá trình này hoàn tất:

Refinement done.
Saved digest_v2.pdf (52,418 bytes)

Mở digest_v2.pdf rồi so sánh với digest.pdf. Giờ đây, mỗi câu chuyện sẽ có thêm dòng "Tại sao điều này lại quan trọng".

8. Duy trì Cấu hình tác nhân được quản lý

Cho đến nay, mọi lệnh gọi đều đã truyền AGENTS.md, SKILL.md và generate_pdf.py nội tuyến. Cách này có hiệu quả, nhưng mã gọi của bạn sẽ mang theo toàn bộ nội dung tệp trong mỗi lần chạy. agents.create() sẽ tích hợp cấu hình vào một tác nhân có tên đã lưu ở phía Google. Lần gọi tiếp theo chỉ truyền mã nhận dạng tác nhân:

Inline calls:   send sources on every call
Named agent:    bake once → invoke by ID, no sources

Thông tin cần điền

Mở save_agent.py. Có một việc cần làm (TODO 1).

Xin lưu ý rằng các hằng số được nhập trực tiếp từ run_digest.py (không trùng lặp):

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

TODO 1: điền vào lệnh gọi agents.create():

agent = client.agents.create(
    id="my-digest",
    base_agent=BASE_AGENT,
    description="Daily tech digest with editorial voice and PDF generation.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

base_environment (không phải environment) là điểm khác biệt chính so với lệnh gọi nội tuyến ở bước trước: các nguồn được lưu trữ ở phía Google và tự động gắn kết trong mọi lệnh gọi trong tương lai. Chạy một lần, không chạy trên mọi lần chạy bản tóm tắt.

Xác minh: lưu tác nhân

uv run python save_agent.py

Saved: my-digest
my-digest: Daily tech digest with editorial voice and PDF generation.

Gọi tác nhân đã lưu

Mở invoke_agent.py. Thao tác này gọi tác nhân đã lưu theo mã nhận dạng mà không có nguồn:

stream = client.interactions.create(
    agent="my-digest",
    input="",
    stream=True,
    environment="remote",
)

So sánh điều này với lệnh gọi cùng dòng: agent=BASE_AGENT được thay thế bằng "my-digest" và khối environment đầy đủ với 3 nguồn cùng dòng được thay thế bằng environment="remote". Cấu hình đã được tích hợp sẵn ở phía Google.

Xác minh: gọi tác nhân đã lưu

uv run python invoke_agent.py

Bạn sẽ thấy sự kiện phát trực tiếp giống như khi chạy nội tuyến, nhưng lệnh gọi không có tệp nguồn. Sau khi chạy, ENVIRONMENT_ID và INTERACTION_ID trong .env sẽ được cập nhật để bạn có thể tiếp tục với refine_digest.py như trước.

[agent started]
  [tool] read_file
  [tool] write_file
  [tool] run_code
I have successfully created today's tech news digest.
Done. environment_id=9a1c3e02-...

9. Dọn dẹp

Hộp cát sẽ tự động hết hạn sau 7 ngày không hoạt động. Không có máy chủ nào để dừng. Không có vùng chứa nào để xoá.

Nếu bạn đã lưu một cấu hình tác nhân, hãy xoá cấu hình đó:

uv run python delete_agent.py

10. Tóm tắt

Bạn đã tạo một tác nhân được quản lý từ đầu, từng khái niệm một. Sau đây là nội dung của từng bài tập:

Bài tập

Khái niệm

Key API

Thực hiện cuộc gọi đầu tiên

Cung cấp một hộp cát Linux thực và phát trực tiếp các sự kiện của hộp cát đó

interactions.create(agent, input, environment, stream=True), event.event_type

Tuỳ chỉnh tác nhân

Gắn kết các tệp cấu hình; duy trì mã nhận dạng cho .env trong cùng một lần chạy

environment.sources, set_key

Tải xuống PDF

Tải tệp PDF xuống mà không cần chạy lại tác nhân

Gemini Files API :download trong download_pdf.py

Tiếp tục cuộc trò chuyện

Tiếp tục cuộc trò chuyện mà không cần tìm nạp lại thông tin trên web

environment=environment_id, previous_interaction_id=interaction_id

Duy trì cấu hình tác nhân

Duy trì cấu hình tác nhân; gọi theo mã nhận dạng, không cần nguồn

agents.create(), agents.list()

Các mẫu chính

  1. Một lệnh gọi, một hộp cát: interactions.create() xử lý tất cả cơ sở hạ tầng (không có vùng chứa để triển khai, không có gói để cài đặt cục bộ)
  2. Phát trực tuyến liên tục: stream=True biến một hộp đen 90 giây thành nguồn cấp dữ liệu trực tiếp gồm các lệnh gọi công cụ và đoạn văn bản
  3. Nguồn nội tuyến: gắn AGENTS.md, SKILL.md và các tập lệnh dựng sẵn vào hộp cát mà không cần thực hiện bước tải lên hoặc triển khai
  4. Khai thác tính năng tự động phát hiện: các tệp được đặt trong .agents/ sẽ tự động được chọn (không cần định cấu hình SDK)
  5. Trạng thái hai chiều: environment_id theo dõi các tệp và gói; previous_interaction_id theo dõi bối cảnh cuộc trò chuyện; có thể truyền độc lập cả hai
  6. Tải nhanh xuống: môi trường là một tệp tar hệ thống tệp đầy đủ, có thể truy cập thông qua Gemini Files API
  7. Tác nhân được đặt tên: agents.create() cố định cấu hình; các lệnh gọi trong tương lai chỉ truyền mã nhận dạng tác nhân và environment="remote", không có nguồn

ADK + Cloud Run so với Tác nhân được quản lý: xem nhanh điểm khác biệt

Chức năng

ADK + Cloud Run

Các tác nhân được quản lý trên Gemini API

Cung cấp hộp cát

docker build + gcloud run deploy

interactions.create()

Xác định công cụ

Các hàm Python đã đăng ký với tác nhân

Được tích hợp sẵn: duyệt web, thực thi mã, hệ thống tệp

Cài đặt gói

pip install trong Dockerfile

Tác nhân chạy pip install bên trong hộp cát

Sự kiện phát trực tiếp

Cơ sở hạ tầng SSE tuỳ chỉnh

stream=True

Tiếp tục một phiên

Cơ sở dữ liệu phiên + truyền bối cảnh

environment_id + previous_interaction_id

Tệp cấu hình

Được mã hoá cứng trong tác nhân hoặc được chèn khi khởi động

Được gắn qua environment.sources

Cơ sở hạ tầng cần quản lý

Vùng chứa, Cloud Run, IAM, bí mật

Không có

Các bước tiếp theo