Xây dựng agent được quản lý đầu tiên của bạn

📖 Nội dung bài học

Video

Xây dựng agent được quản lý đầu tiên của bạn

Nếu bạn đã từng tự xây dựng một vòng lặp agent, bạn sẽ biết quy trình: vòng lặp while, các câu lệnh switch dựa trên lý do dừng, thực thi công cụ. Cách đó hoạt động tốt, và đối với nhiều tính năng, đó thực sự là cấu trúc phù hợp. Nhưng đôi khi vòng lặp đó sẽ chạy rất lâu — vài phút, có thể hàng giờ — qua nhiều công cụ, với trạng thái cần lưu giữ, tệp cần ghi, và công việc cần tiếp tục sau một trục trặc mạng. Tại thời điểm đó, bạn không muốn chạy vòng lặp trên máy chủ của mình. Bạn muốn ủy thác nó. Đó chính là managed agents (agent được quản lý).

Managed agent là gì?

Managed agent là một vòng lặp agent chạy trên cơ sở hạ tầng của Anthropic thay vì của bạn. Bạn mô tả agent một lần, cung cấp cho nó một môi trường để hoạt động, và bạn bắt đầu một phiên. Anthropic chạy vòng lặp, và bạn chỉ cần stream các sự kiện trở lại khi nó hoạt động.

Managed agents được bật mặc định cho mọi tài khoản API — không cần truy cập đặc biệt.

Bốn nguyên tắc cơ bản

Có bốn nguyên tắc cơ bản, và chúng đi theo thứ tự:

Agent — nhân cách: model, system prompt, và bộ công cụ (toolset). Cái này có thể tái sử dụng qua nhiều lần chạy.
Environment — nơi agent hoạt động: cloud hoặc local, cấu hình mạng, v.v.
Session — một lần chạy duy nhất của agent trong một môi trường nhất định. Session là đơn vị công việc.
Events — các thông điệp đi vào và đi ra: hành động của agent, các lệnh gọi công cụ (tool calls), kết quả, các phản hồi.

Đây là cách các thành phần kết hợp với nhau: ứng dụng của bạn nói chuyện với một session, session điều khiển công việc bên trong environment, và mọi thứ xảy ra đều chảy ngược ra ngoài qua luồng sự kiện (event stream):

Sơ đồ kiến trúc cho thấy một agent được kết nối với một Session, điều khiển một Environment, với kết quả chảy ngược qua Luồng Sự kiện (Event Stream) về ứng dụng của bạn

Lưu ý sự thay đổi ở đây: bạn không chạy vòng lặp while. Bạn gửi sự kiện và đọc sự kiện.

Managed agent nhỏ nhất có thể

Hãy xây dựng managed agent nhỏ nhất có thể thực hiện một việc hữu ích: tạo một tệp trong thư mục tạm (temp drive), đếm số dòng của nó, và báo cáo lại.

Đối với các công cụ, chúng ta sẽ sử dụng agent toolset — các công cụ tệp, bash và web được Anthropic đóng gói sẵn. Chúng hoạt động tốt cho tác vụ này, vì vậy chúng ta không cần tự định nghĩa bất kỳ công cụ nào.

Bước 1: Tạo agent

Đầu tiên, chúng ta tạo agent. Lưu ý agent toolset được định nghĩa ngay trong mảng tools — đó là bộ công cụ được đóng gói:

import anthropic

client = anthropic.Anthropic()

agent = client.beta.agents.create(
    name="Line Counter",
    model="claude-opus-4-8",
    system="You are a helpful agent that completes small file tasks.",
    tools=[
        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}
    ],
)

Hãy nhớ: agent có thể tái sử dụng. Tạo nó một lần và chạy nó qua nhiều session.

Bước 2: Tạo environment

Tiếp theo, environment. Cái này khởi động mẫu container — cloud, với mạng không hạn chế. Đây là môi trường sandbox nơi tệp thực sự được ghi:

environment = client.beta.environments.create(
    name="line-counter-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

Bước 3: Tạo session

Sau đó chúng ta tạo một session với agent và environment của chúng ta, cộng với một tiêu đề tùy chọn. Session là đơn vị công việc:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Count lines demo",
)

Bước 4: Mở luồng stream, sau đó gửi thông điệp khởi đầu

Bây giờ chúng ta mở luồng sự kiện — và lưu ý rằng chúng ta làm điều này trước tiên. Luồng chỉ cung cấp các sự kiện xảy ra sau khi nó mở, vì vậy hãy luôn mở nó trước khi gửi thông điệp khởi đầu. Sau đó, chúng ta gửi thông điệp người dùng vào luồng trực tiếp:

with client.beta.sessions.events.stream(session_id=session.id) as stream:
    # Luồng đã mở — bây giờ gửi thông điệp khởi đầu
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Create a file in the temp directory, "
                                "count its lines, and report back.",
                    }
                ],
            }
        ],
    )

Lưu ý là events — số nhiều. Events là cách mọi thứ chảy trong API này.

Bước 5: Tiêu thụ luồng stream

Cuối cùng, chúng ta tiêu thụ luồng stream. Có ba loại sự kiện quan trọng cho bản demo này:

agent.message — văn bản của Claude
agent.tool_use — công cụ mà Claude đã chọn
session.status_idle — agent đã hoàn thành

    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "agent.tool_use":
            print(f"\n[tool] {event.name}")
        elif event.type == "session.status_idle":
            print("\n--- Agent done ---")
            break

Chạy nó, và kết quả là agent đang suy luận thành tiếng — văn bản thực tế, các công cụ nó chọn, và một câu trả lời cuối cùng. Tất cả đều chạy bên trong container của Anthropic, không phải của bạn:

Kết quả đầu ra của terminal từ lần chạy managed agent: ID agent, environment và session được tạo, sau đó luồng sự kiện hiển thị agent ghi tệp, chạy các công cụ của nó và báo cáo rằng tệp chứa 3 dòng

Sự đánh đổi

Thông thường với agent, chúng ta có vòng lặp của riêng mình nơi chúng ta phải kiểm soát mọi thứ. Với managed agents, bạn ủy thác vòng lặp đó, môi trường sandbox, và khả năng tiếp tục — và chỉ cần tiêu thụ luồng sự kiện khi nó đến.

Trong một ứng dụng sản xuất, đây là cấu trúc phù hợp cho các tác vụ chạy dài, thao tác tệp, "hãy tổ chức cái này cho tôi". Hãy tưởng tượng việc dọn dẹp chia sẻ tệp: một managed agent đọc đặc tả cấu trúc thư mục đích, duyệt qua thư mục đầu vào lộn xộn, di chuyển tệp vào các thư mục dự án phù hợp, lưu trữ các bản sao và rác dung lượng bằng không, và đánh dấu bất kỳ thứ gì nó không thể đặt một cách chắc chắn — tất cả trong một session có thể chạy trong nhiều phút đối với hàng nghìn tệp. Đây là hình ảnh của nó trong một ứng dụng thực tế — một bảng điều khiển dọn dẹp chia sẻ tệp stream hoạt động của agent trực tiếp khi nó sắp xếp, lưu trữ và đánh dấu các tệp:

Một ứng dụng web dọn dẹp chia sẻ tệp được cung cấp bởi managed agent, hiển thị cây thư mục đang được sắp xếp cùng với nguồn cấp dữ liệu hoạt động trực tiếp của các sự kiện của agent khi nó di chuyển và lưu trữ các tệp

Tóm tắt

Managed agents là vòng lặp agent, được chạy cho bạn — trên cơ sở hạ tầng của Anthropic thay vì máy chủ của bạn.
Luồng hoạt động là: tạo agent, tạo environment, tạo session, gửi sự kiện vào, và stream sự kiện ra.
Agent (model, system prompt, toolset) có thể tái sử dụng qua các lần chạy; session là một lần chạy duy nhất; events là cách mọi thứ chảy.
Mở luồng sự kiện trước khi gửi thông điệp khởi đầu của bạn — nó chỉ cung cấp các sự kiện xảy ra sau khi nó mở.
Theo dõi ba loại sự kiện: agent.message (văn bản), agent.tool_use (lựa chọn công cụ), và session.status_idle (hoàn thành).
Sử dụng managed agents khi vòng lặp sẽ chạy quá lâu, làm quá nhiều việc, hoặc cần tồn tại sau một trục trặc. Sử dụng vòng lặp thủ công khi bạn muốn kiểm soát hoàn toàn.

🎬 Bản ghi video

Source video: 1Rl3gZrlQJo

Không có transcript — xem phần nội dung bài học bên trên.

🔁 Bài học liên quan

Bài tiếp: Building with Claude Code
Bài trước: What are managed agents?
Thuộc lộ trình: Path C
Docs tham khảo: Glossary · Skills atlas · By use-case

📚 Nguồn & ghi nhận

Bài học gốc Anthropic Academy: https://anthropic.skilljar.com/claude-platform-101/486264
Crawl: 2026-06-27 · Chuẩn hoá: 2026-06-27