Biến Claude Code thành đội AI agent cá nhân

1. Kaya: trợ lý AI cá nhân dựng trên Claude Agent SDK

Người dẫn kênh miss google mở đầu bằng lời chào và nói rằng hôm nay anh rất hào hứng muốn chia sẻ, và hy vọng mở rộng cách mọi người nhìn về những gì làm được với AI agent ở thời điểm quay video (video đăng ngày 06/10/2026). Anh sẽ cho xem một trợ lý AI cá nhân (personal AI assistant) mà anh tự build bằng Claude Agent SDK.

Theo lời anh trong video đăng ngày 06/10/2026, đây là một phiên bản đã được đơn giản hoá, nhưng vẫn "siêu mạnh", của một trợ lý cá nhân thật mà anh dùng mỗi ngày cho công việc thường nhật, dù là việc cá nhân, việc ở chỗ làm hay việc kinh doanh của anh. Để giới thiệu và dạy cách tự build bằng Claude Agent SDK, anh dùng bản rút gọn này.

2. Demo: ba việc giao cùng lúc, ba subagent chạy song song

"Hãy xem nó chạy thế nào", anh nói. Anh nhờ Kaya, tên của trợ lý, làm vài việc mà bình thường anh vẫn tự làm trong ngày. Yêu cầu gồm ba phần (demo trong video đăng ngày 06/10/2026):

1. Xem YouTube analytics của anh và cho biết video đăng gần nhất của anh đang chạy ra sao; đọc cả phần bình luận, vì anh muốn hiểu người xem đang nói gì.
2. Tìm hiểu đâu là những công cụ AI tốt cho người làm nội dung (content creator): anh muốn biết mình có thể dùng công cụ nào để cải thiện quy trình làm nội dung cho YouTube.
3. Viết một guide thực hành về cách implement hooks trong Claude Agent SDK, và nhớ đọc tài liệu chính thức.

Gửi đi xong, ngay lập tức các assistant message cùng các tool call và tool response bắt đầu được stream về màn hình (demo trong video đăng ngày 06/10/2026). Anh chỉ ra rằng có nhiều subagent đang được gọi, và tất cả đều chạy song song.

Theo anh (video đăng ngày 06/10/2026), cái hay của Claude Agent SDK là nó được xây trên Claude Code, mà Claude Code có subagent: agent chính có thể sinh ra (spawn) một loạt subagent khác nhau để làm nhiều việc song song, và anh nói điều đó tăng output và năng suất "theo cấp số nhân".

Trên màn hình lúc đó là một YouTube analyst chuyên biệt có quyền dùng Playwright, nên nó tự mở được browser và tự điều khiển browser. Đó là cửa sổ bên phải: anh nói anh không làm gì cả, chính analyst đang điều hướng browser để xem analytics và tìm hiểu video của anh đang chạy thế nào (demo trong video đăng ngày 06/10/2026). Ở những output khác, chẳng hạn các khối WebFetch, là kết quả tìm kiếm do researcher gửi về, vì researcher đang search web.

Tất cả những agent đó làm việc song song nên mọi thứ nhanh hơn nhiều, và anh gọi đó là một phần rất tuyệt của Claude Code (theo anh, video đăng ngày 06/10/2026).

3. Vì sao dựng agent trên nền Claude Code

Anh đặt câu hỏi: nếu nghĩ xem đâu là AI agent mạnh nhất, giỏi nhất mà bạn biết, thì có lẽ đó là Claude Code, đúng không? Theo anh (video đăng ngày 06/10/2026), đó chính là động lực để dùng Agent SDK. Anh nói lúc đầu anh hơi hoài nghi không biết thư viện này thực ra hữu ích ở chỗ nào.

Nhưng khi nghĩ kỹ, với rất nhiều người đang build AI agent, nhất là cho những use case như thế này, nơi anh muốn build một thứ thật mạnh và thật nhanh cho riêng mình dùng, thì xây trên một thứ như Claude Code là rất hợp lý, vì theo anh (video đăng ngày 06/10/2026) đó là AI agent mạnh nhất mà chúng ta đang được dùng.

Theo cách anh mô tả trong video đăng ngày 06/10/2026, về cơ bản Agent SDK trừu tượng hoá vừa đủ để bạn không phải tự build agent loop. Bạn để "dân chuyên nghiệp", anh gọi là "những GOAT ở Anthropic", lo phần đó; anh nói họ đã build agent loop tốt nhất. Kết quả là bạn dùng Claude Code như một khối xây dựng (building block) để tuỳ biến và dựng một hệ thống cao cấp hơn, mạnh hơn.

Đó là thứ Agent SDK cho phép, theo anh (video đăng ngày 06/10/2026): lấy Claude Code và biến nó thành thứ cực kỳ chuyên biệt cho từng nhiệm vụ cụ thể, mà vẫn giữ được cái hay của toàn bộ harness và kiến trúc Anthropic đã dựng quanh Claude Code để nó mạnh đến vậy. Phần còn lại của video sẽ cho thấy chính xác cách tạo ra một hệ thống như thế.

Anh để demo tiếp tục chạy và tua nhanh tới kết quả cuối để xem trợ lý cá nhân làm tốt tới đâu.

4. Kết quả thứ nhất: báo cáo YouTube và phân tích bình luận

Khi chạy xong, assistant message cuối cùng báo ba việc đã hoàn tất (demo trong video đăng ngày 06/10/2026). Có báo cáo YouTube analytics, kèm một bản tóm tắt cấp cao nhắc riêng tới phần bình luận, đúng như yêu cầu, và anh nói "vậy là tốt". Có báo cáo nghiên cứu về công cụ AI, việc thứ hai, nằm trong một file markdown đầy đủ. Và cuối cùng là một guide về cách implement hooks trong Claude Agent SDK.

Anh chuyển sang thư mục của project để lướt nhanh từng output. Ở báo cáo YouTube, có rất nhiều chỉ số được kéo ra từ dashboard YouTube Analytics, đi riêng vào chi tiết của đúng một video: tăng trưởng lượng người theo dõi kênh, phân tích theo các nguồn traffic khác nhau, nên anh nhận xét phần số liệu khá chi tiết (demo trong video đăng ngày 06/10/2026).

Tiếp theo là một phần phân tích riêng về bình luận. Theo anh (video đăng ngày 06/10/2026), phần này rất tuyệt, vì khi có nhiều video mà phải tự đọc hết bình luận để nắm xu hướng chung thì nhiều lúc rất khó, nhất là với những video có nhiều bình luận hơn. Nên có được kiểu phân tích cảm xúc (sentiment analysis) như thế này là "một điều rất lớn".

Anh gửi lời cảm ơn tới những người đã xem và bình luận, và nói anh rất trân trọng phản hồi. Báo cáo có một số insight rút từ bình luận, ví dụ người xem đánh giá rất cao cách làm "from scratch", tức tự dựng từ đầu (demo trong video đăng ngày 06/10/2026). Anh nói có cả loạt insight thú vị, thậm chí cả đề xuất về những nội dung anh nên làm tiếp, và thấy như vậy rất hay.

5. Báo cáo công cụ AI và guide về hooks

Tiếp đó anh mở báo cáo của researcher về công cụ AI (demo trong video đăng ngày 06/10/2026). Báo cáo có mục lục cho các phần khác nhau, rồi một bảng phân tích những công cụ hàng đầu nên dùng. Cuộn xuống, anh thấy hay ở chỗ có link tới rất nhiều nguồn. "Wow, cái này dài thật", anh nói; đây là một bản phân tích rất lớn. Có phần khuyến nghị cuối cùng, gồm cả một phép tính ROI. Và dưới cùng là toàn bộ citations, thứ mà anh và nhóm đã đưa vào system prompt của riêng subagent này.

Anh chỉ ra rằng nó đã đọc rất nhiều website khác nhau để gom thông tin, và gọi đó là "deep research agent của riêng bạn" trong Claude Agent SDK (demo trong video đăng ngày 06/10/2026).

Rồi tới guide implement hooks bằng Agent SDK, ví dụ hook PostToolUse. Anh nói anh có thể khẳng định, dựa vào tài liệu chính thức, rằng tất cả những gì trong đó đều đúng (theo anh, video đăng ngày 06/10/2026). Để implement hooks có những mục cụ thể, như PostToolUse, UserPromptSubmit, và anh nói tất cả đều bám đúng tài liệu. Anh nói thêm rằng guide còn có cả code example lấy từ tài liệu, điều anh thấy rất hay.

Theo anh (video đăng ngày 06/10/2026), khi đã có guide này trong project, một guide trích riêng phần hooks từ tài liệu chính thức online, bạn có thể bắt tay implement đúng tính năng đó, hoàn toàn bám vào code example thật từ chính nguồn, từ chính đội phát triển. Anh gọi đây là một cách rất mạnh để implement tính năng mới mà không để model "bịa" (hallucinate).

Đó chỉ là một ví dụ đơn giản về việc chạy ba nhiệm vụ song song, rồi có thể bỏ đi chỗ khác và để trợ lý cá nhân tự lo (demo trong video đăng ngày 06/10/2026). Anh nói ba việc này mới chỉ là "giọt nước trong xô": theo anh, bạn có thể thêm rất nhiều chức năng cho trợ lý cá nhân bằng MCP server, phần sẽ được hướng dẫn cụ thể sau, và tận dụng thật tốt subagent cho các workflow chuyên biệt.

6. Cái giá của một thư viện high-level

Trong video đăng ngày 06/10/2026, anh nói nhanh về đánh đổi (trade-off) khi dùng một thư viện rất high-level như Claude Agent SDK so với build bằng một framework tầng thấp hơn. Ví dụ, nếu build AI agent từ đầu, gọi thẳng API, bạn có toàn quyền kiểm soát agent loop, cách gọi tool, cách điều phối (orchestrate) các agent, tức cách truyền state hay dữ liệu giữa các agent nếu đó là hệ multi-agent.

Khi chuyển sang một framework như Agent SDK, theo anh (video đăng ngày 06/10/2026), bạn mất toàn bộ quyền kiểm soát đó, vì đây là thư viện ở tầng cao hơn nhiều. Bạn để "những người giỏi nhất" lo hết phần ấy, và thứ bạn thực sự tập trung khi dùng Agent SDK là build business logic trên một agent rất mạnh là Claude Code.

Với rất nhiều use case như cái anh vừa nói, nơi anh muốn có một thứ chạy được ngay, mạnh sẵn "out of the box" mà không tốn hàng đống thời gian build từ đầu, anh cho đây là một giải pháp rất tốt (theo anh, video đăng ngày 06/10/2026). Anh kể càng làm project trợ lý cá nhân này, anh càng "phải lòng" thư viện. Nếu bạn đã dùng Claude Code, anh chắc bạn sẽ rất thích dùng SDK; còn nếu bạn hoàn toàn mới với Agent SDK, thậm chí mới với Claude Code, cũng không sao, anh sẽ hướng dẫn từng bước từ đầu tới cuối cách build một AI agent cá nhân mạnh như vậy.

7. Chuẩn bị project: repo, uv, Claude Code, Chrome, Node

Để bắt đầu, anh bảo vào repo tên claude-agent-sdk-intro và clone về máy. Danh sách cần cài, theo video đăng ngày 06/10/2026:

• uv, công cụ anh dùng để quản lý project Python (theo video đăng ngày 06/10/2026).
• Claude Code, cài bằng lệnh npm trong README, rồi xác thực (authenticate) qua Claude Code CLI sau khi cài (theo video đăng ngày 06/10/2026).
• Chrome, cần cho Playwright MCP để dùng được browser của bạn (theo video đăng ngày 06/10/2026).
• Node, cần cho cả Playwright lẫn Claude Code (theo video đăng ngày 06/10/2026).

Theo video đăng ngày 06/10/2026, nếu bạn đã xác thực qua Claude Code CLI thì không phải đặt Anthropic API key. Trừ khi bạn muốn dùng API key, khi đó vào Claude Console tạo một API key mới; tuỳ bạn chọn. Cài đủ mọi thứ và clone repo xong, bạn cd vào thư mục rồi chạy uv sync để dựng virtual environment và cài dependency. Nếu dùng API key, bạn đặt nó trong file .env ở thư mục gốc. Các lệnh dưới đây chép từ README của repo (đọc ngày 25/10/2026):

npm install -g @anthropic-ai/claude-code

git clone https://github.com/kenneth-liao/claude-agent-sdk-intro
cd claude-agent-sdk-intro
uv sync

ANTHROPIC_API_KEY=your_api_key_here

Rồi có thể bắt đầu chạy code. Anh sẽ đi qua từng khái niệm cốt lõi một. Repo có bảy module, và khi xong phần subagent ở module 6, bạn sẽ có trọn vẹn trợ lý cá nhân để tự tuỳ biến (theo video đăng ngày 06/10/2026).

8. Hai cách nói chuyện với agent: query và ClaudeSDKClient

Anh nhắc lại về mặt khái niệm điều đang diễn ra: agent loop do SDK chạy. Nếu hình dung agent loop gồm nhận một query từ người dùng, lên plan cho việc muốn làm, có thể gọi một tool, nhận tool response, rồi quyết định có trả lời người dùng hay chưa, v.v., thì tất cả diễn ra phía sau và do Claude Code lo (theo video đăng ngày 06/10/2026). Khi tất cả xong, khi agent loop kết thúc, lúc đó ta mới nhận được response.

Theo video đăng ngày 06/10/2026, có hai cách tương tác với Claude Code agent trong SDK: hàm query và ClaudeSDKClient. Khác biệt là query có thể hiểu như một truy vấn stateless: giữa các lần query, cuộc hội thoại trước không được giữ lại. Còn với ClaudeSDKClient, bạn kết nối tới một client để gửi nhiều query, qua lại với agent và tiếp tục cuộc hội thoại trong cùng một session.

Trong file 0_querying.py, phần trên cùng chỉ định nghĩa một hằng số cho model muốn dùng, ở đây là Haiku, model rẻ hơn, và cấu hình nó trong class ClaudeAgentOptions. Anh nói sẽ đi sâu hơn nhiều vào options sau, nhưng về cơ bản đây là thứ cho phép bạn cấu hình Claude Code cho agent và use case riêng của mình (theo video đăng ngày 06/10/2026).

Theo video đăng ngày 06/10/2026, ví dụ đầu tiên chạy một query đơn giản: gửi "Hi" làm prompt và truyền vào object options đã định nghĩa ở trên. Thứ nhận lại là một async iterator trả ra (yield) các message, nên chỉ việc lặp qua từng message và in message thô ra. Với client thì rất giống: điểm khác duy nhất là dựng client như một context manager, theo pattern async with ClaudeSDKClient(...) as client, cũng truyền options vào. Trong context đó, bắn một query, rồi lặp qua các message nhận về bằng cách gọi receive_response, hàm này yield toàn bộ message từ client khi chúng stream về, và lại in message thô.

Phần cốt lõi của file, chép từ repo (đọc ngày 25/10/2026), khớp với màn hình trong video:

MODEL="haiku"


async def main():
    # Use ClaudeAgentOptions to configure the agent's behavior, we'll cover this in more detail later
    # Here we just simply swap to a cheaper model
    options = ClaudeAgentOptions(
        model=MODEL,
    )

    input_prompt = "Hi"
    print(f"User: {input_prompt}")

    print("Example using `query()`")
    async for message in query(prompt=input_prompt, options=options):
        print(message)

    print(30*"=")
    print("Example using `ClaudeSDKClient`")
    # 2.1 Use context manager to handle connection and disconnection with proper cleanup
    async with ClaudeSDKClient(options=options) as client:

        # 2.2. Send a query
        await client.query(input_prompt)

        # 2.3 Receive messages including ResultMessage
        async for message in client.receive_response():
            print(message)

Anh nói khá đơn giản: theo anh (video đăng ngày 06/10/2026), với hầu hết mục đích bạn sẽ luôn muốn dùng client; query thật ra chỉ dành cho tình huống một lần, khi bạn chỉ cần một response duy nhất.

9. Đọc các message trả về: system, assistant, result và cache

Anh chạy file và xem bản in ra (demo trong video đăng ngày 06/10/2026). Đầu tiên là user query "Hi", ví dụ dùng query. Thứ nhận về là các object message thô, với nhiều loại message khác nhau. Message đầu là system message, có phần data. Theo video đăng ngày 06/10/2026, system message luôn được gửi về ở đầu response, tức đó là message đầu tiên bạn nhận mỗi lần gửi query, và nó rất hữu ích vì cho thấy toàn bộ cấu hình của agent, thứ mà như sẽ thấy sau, được định nghĩa bằng options bạn truyền vào.

Trong đó có thể thấy mọi tool agent đang có: theo video đăng ngày 06/10/2026, mặc định agent được dùng toàn bộ tool của Claude Code. Cũng thấy các MCP server đang kết nối (lúc này chưa có cái nào), model đã chọn, permission mode, và các slash command có sẵn mặc định như compact, context: anh nói nếu đã dùng Claude Code thì đây là những slash command bạn có ngay. Cuối cùng là các subagent trong key agents: anh chỉ ra rằng kể cả khi bạn không tạo subagent nào, Claude Code vẫn có một số subagent định nghĩa sẵn để dùng (theo video đăng ngày 06/10/2026).

Sau system message là chuỗi assistant message, user message, tool message, v.v. Ở đây là response của assistant, và cuối cùng là result message. Giống system message, theo video đăng ngày 06/10/2026, result message luôn là message cuối cùng bạn nhận được mỗi lần gửi query, và nó cho biết kết quả của lượt chạy đó. Có session ID để theo dõi hội thoại: khi có thêm các lượt với agent, ta có thể lần lại toàn bộ hội thoại trong log nhờ giữ session ID này. Và cuối cùng là usage cùng tổng chi phí (total cost) của session tính tới thời điểm đó.

Tiếp theo là ví dụ dùng client, và nó y hệt (demo trong video đăng ngày 06/10/2026). Vì chỉ chạy một query với client nên không có qua lại nhiều lượt, kết quả giống hệt: system message, response của assistant, rồi result message.

Nếu để ý kỹ, anh nhắc, cả hai cách đều gửi cùng một input prompt, chỉ là "Hi". Nhưng chi phí ở result message thứ hai, khi gọi qua client, thấp hơn khoảng một bậc độ lớn (order of magnitude) so với lần query đầu (số đo trong video đăng ngày 06/10/2026). Lý do, theo anh, là lần đầu đã tạo cache cho các input token, và lần sau dùng lại token đã cache nên rẻ hơn nhiều. Anh nói mặc định caching luôn bật trong API và trong Claude Code (theo video đăng ngày 06/10/2026).

Đó là phần query. Từ đây trở đi anh luôn dùng client, vì như anh đã nói (video đăng ngày 06/10/2026), nó có statefulness, hữu ích hơn nhiều khi build những agent mà ta muốn trò chuyện liên tục và giao việc.

10. Module messages: in message cho dễ đọc

Sang module messages, anh nói (video đăng ngày 06/10/2026) phần này không thật sự cốt lõi với chức năng của SDK. Anh chỉ muốn cho thấy cách parse các message nhận về từ client, và điều đó giúp file agent chính gọn đi đáng kể.

Có một file tên cli_tools.py, chứa vài hàm tiện ích để in message ra cho đẹp. Sau này, như sẽ thấy, file đó cũng parse tham số từ terminal: khi chạy các file, ta có thể chỉ định lúc chạy (runtime) là muốn dùng một model khác, hay in message thô chẳng hạn. Trong file có phần chỉ định style để in từng loại message, rồi bên dưới là hàm parse_and_print_message, parse các loại message khác nhau: system message, assistant message, text block, tool use block, thinking block, v.v. Theo video đăng ngày 06/10/2026, các object này đến từ Claude Agent SDK, tức là những kiểu message cụ thể của SDK.

Quay lại module messages, file chỉ dùng hai hàm đó: print_rich_message và parse_and_print_message. Mọi thứ khác giữ nguyên, nhưng nhờ vậy file gọn hơn hẳn, và toàn bộ phần tương tác với agent nằm trong chưa tới 50 dòng code (theo video đăng ngày 06/10/2026).

Mở terminal, anh chạy lệnh dưới đây, và giờ các message được in thành những panel "rich" rất đẹp, dễ đọc hơn và dễ phân biệt message nào đến từ nguồn nào (demo trong video đăng ngày 06/10/2026):

uv run 1_messages.py

11. Custom tool qua một MCP server chạy in-process

Tiếp theo là tools, hay "custom tools" như tài liệu gọi. Theo video đăng ngày 06/10/2026, cách định nghĩa tool với SDK rất giống các framework khác như LangChain, LangGraph hay OpenAI SDK: có hàm decorator tool, dùng được trên bất kỳ hàm Python nào để biến nó thành một tool cho SDK. Thứ còn lại là hàm create_sdk_mcp_server.

Điều thú vị khi dùng tool với Agent SDK, theo anh (video đăng ngày 06/10/2026), là mọi tool đều phải được implement trong một SDK server chạy in-process, nhưng anh nói rất đơn giản, sẽ thấy ngay.

Đầu tiên là định nghĩa tool. Cho ví dụ này anh tạo thư mục db với file products.json để giả lập một database. Hàm tool là một hàm bình thường, và tất nhiên ta muốn tool là async để agent dùng song song được: chúng có thể gọi tool nhiều lần cùng lúc, giúp agent chạy nhanh hơn nhiều (theo video đăng ngày 06/10/2026).

Tool search_products nhận một tham số args, là một dictionary chứa input, và cũng trả về một dictionary. Theo video đăng ngày 06/10/2026, đây chỉ là quy ước của Agent SDK: bạn luôn theo pattern chỉ định một dictionary args chung. Chỗ thật sự khai báo tham số input là ở decorator phía trên: tên tool (có thể trùng tên hàm), mô tả tool, rồi một dictionary các tham số input với tên và kiểu dữ liệu. Có nhiều tham số hơn thì cứ thêm vào dictionary; ở đây chỉ có một, nên trong hàm ta parse nó ra để lấy query, rồi tìm đơn giản trong file JSON sản phẩm.

Định nghĩa xong tool (có thể thêm các tool khác như tạo sản phẩm mới hay xoá sản phẩm), ta dùng create_sdk_mcp_server để định nghĩa một server. Theo video đăng ngày 06/10/2026, server này chạy in-process, tức chạy cùng script Python. Khai báo rất đơn giản: truyền một tên, có thể chỉ định version, rồi danh sách tool vừa định nghĩa bằng decorator.

Theo video đăng ngày 06/10/2026, có tool và server rồi thì việc tiếp theo là truyền nó vào qua ClaudeAgentOptions, vì như đã nói, options là cách cấu hình agent. Ở đây chỉ cần truyền một dictionary với tên server và object server như đã định nghĩa. Nếu có nhiều MCP server, hai hay ba cái, cứ thêm vào dictionary này.

Điều anh nhấn mạnh là rất quan trọng (theo video đăng ngày 06/10/2026): khi thêm MCP server, các tool trong đó không được cho phép mặc định. Agent có thể thấy là nó có những MCP đó, nhưng nếu thử chạy một tool từ các MCP server ấy, nó sẽ gặp lỗi permission. Muốn dùng được, bạn phải thêm rõ ràng tool vào danh sách allowed_tools, và tên tool có quy ước rất cụ thể: tiền tố mcp, hai dấu gạch dưới, tên MCP server, lại hai dấu gạch dưới, rồi tên tool. Ở ví dụ này tool tên search_products dùng dấu gạch dưới; nếu đặt tên bằng dấu gạch ngang thì tên ở dưới cũng phải đổi theo, tức phải khớp chính xác với tên đã khai báo phía trên.

Đoạn code dưới đây chép từ file 2_tools.py trong repo (đọc ngày 25/10/2026), khớp với màn hình; phần thân tìm kiếm được lược bằng dấu "...":

@tool("search_products", "Search for products in the space toys catalog", {"query": str})
async def search_products(args: dict[str, Any]) -> dict[str, Any]:
    ...

products_server = create_sdk_mcp_server(
    name="products",
    version="1.0.0",
    tools=[search_products]
)

options = ClaudeAgentOptions(
    model=args.model,
    mcp_servers={"products": products_server},
    allowed_tools=["Read", "Write", "mcp__products__search_products"],
    disallowed_tools=["WebSearch", "WebFetch"]
)

Mọi thứ khác giữ nguyên. Theo anh (video đăng ngày 06/10/2026), đó là cái hay của việc agent loop được trừu tượng hoá: khi đi qua các module và thêm tính năng mới, tất cả đều được làm qua agent options. Code phía dưới gần như không đổi, trừ một vòng while sẽ thêm sau để có hội thoại qua lại.

Ví dụ dùng danh mục sản phẩm là đồ chơi trẻ em chủ đề vũ trụ, và prompt là "Find me a telescope for kids". Anh mở terminal và chạy uv run 2_tools.py. Agent gọi tool mcp__products__search_products với query "telescope for kids", nhận về đúng một kết quả, rồi tóm tắt lại thông tin đó (demo trong video đăng ngày 06/10/2026). Tóm lại, để thêm custom tool của riêng mình, ta dùng MCP server in-process đó.

12. ClaudeAgentOptions: model, allowed/disallowed tools và permission mode

Như đã nói, ClaudeAgentOptions là cách cấu hình hành vi của agent, và theo video đăng ngày 06/10/2026 có rất nhiều setting tuỳ biến được. Anh khuyến khích xem tài liệu chính thức về options, còn anh chỉ đi qua những cái anh cho là quan trọng nhất.

Trong video đăng ngày 06/10/2026, đã thấy là ta cấu hình được model cụ thể cho agent. Cũng đã thấy có thể cho phép tool, và có thể chặn hẳn tool bằng danh sách disallowed_tools: ở file 3_options.py, agent không được search web hay lấy dữ liệu từ trang web (WebSearch, WebFetch bị chặn).

Có một setting tên permission mode, anh nói có thể bạn đã quen nếu dùng Claude Code. Theo video đăng ngày 06/10/2026, mặc định là default, nhưng có những preset khác:

• acceptEdits: tự chấp nhận các thay đổi, tức cho phép duyệt trước những tool call như edit hay delete, những thứ sẽ thay đổi file của bạn (theo video đăng ngày 06/10/2026).
• default: hỏi bạn lần đầu tiên chạy bất kỳ tool nào sẽ thay đổi hệ thống, còn tool đọc thì tự được duyệt (theo video đăng ngày 06/10/2026).
• Chế độ planning (plan): không thực thi tool nào (theo video đăng ngày 06/10/2026).
• bypassPermissions: về cơ bản là "YOLO mode", không hỏi quyền cho bất kỳ tool nào (theo video đăng ngày 06/10/2026).

Anh nói thường anh để acceptEdits, nhưng bạn tuỳ biến theo ý mình. Điều cần biết (theo video đăng ngày 06/10/2026) là các setting allowed_tools và disallowed_tools chạy chồng lên trên permission mode. Ví dụ, bạn có tool Edit trong danh sách allowed và dùng permission mode acceptEdits, thì Edit tự được cho phép. Nhưng nếu chuyển Edit xuống danh sách disallowed, dù đang để acceptEdits, tool này rõ ràng vẫn bị chặn. Tức là chúng đè lên bất kỳ permission mode nào bạn đặt.

13. setting_sources, settings và bốn cách sửa system prompt

Tiếp theo là tham số setting_sources, chỉ định nơi nạp setting. Theo video đăng ngày 06/10/2026, giá trị có thể là project hoặc user: nó quyết định có nạp và nạp setting .claude từ đâu.

Nếu đặt là project như trong file, nó tự nạp các file CLAUDE.md: có một file ở thư mục gốc thì file đó được nạp, và ở đó bạn để các quy tắc muốn Claude lần nào cũng theo, hay bất kỳ context nào muốn nó luôn có cho project này. Nó cũng tìm trong thư mục .claude: nếu có settings.json trong đó, như của anh, các setting từ project sẽ được nạp tự động. Trong file của anh có đặt một output style, anh nói sẽ giải thích ngay, và có vài hooks (theo video đăng ngày 06/10/2026).

Nếu đặt là user, theo video đăng ngày 06/10/2026, nó tìm trong thư mục gốc của user, nơi có một thư mục ẩn .claude khác, trong đó cũng có một file settings với những setting khác. Khi đó thay vì nạp setting từ project, nó nạp từ thư mục gốc ấy. Anh giữ project.

Theo video đăng ngày 06/10/2026, ta cũng có thể đặt setting ngay trong code, nếu không muốn nạp từ file, bằng tham số settings, truyền vào một chuỗi JSON. Ví dụ trong file cũng đặt một output style giống trong settings.json, nhưng thay vì "Personal Assistant" thì dùng output style mặc định:

# settings='{"outputStyle": "default"}',

Điều quan trọng cần biết, theo anh (video đăng ngày 06/10/2026): mọi setting đặt ở đây sẽ được ưu tiên hơn setting nạp từ file. Giả sử vẫn giữ dòng nạp setting từ project, file settings.json sẽ được nạp và có output style định nghĩa trong đó; nhưng nếu chuỗi JSON settings cũng chỉ định một output style, cái trong code sẽ thắng cái trong file.

Đây cũng là chỗ tốt để nói về output style. Claude Code có nhiều cách để bạn kiểm soát system prompt. Anh mở một guide trong tài liệu về sửa system prompt (modifying system prompts), có một bảng tóm tắt khá tốt. Theo video đăng ngày 06/10/2026, về cơ bản có bốn cách:

• CLAUDE.md: đã nói ở trên. Nếu project có file này và bạn truyền setting_sources, nó được nạp tự động, và nội dung chỉ được nối thêm (append) vào system prompt (theo video đăng ngày 06/10/2026).
• System prompt ở chế độ append: tương tự, chỉ thêm prompt của bạn vào system prompt sẵn có (theo video đăng ngày 06/10/2026).
• Custom system prompt: thay thế hoàn toàn system prompt của Claude Code, dành cho khi bạn muốn tự viết system prompt từ đầu (theo video đăng ngày 06/10/2026).
• Output style: một kiểu trung gian dễ chịu, nói ở dưới (theo video đăng ngày 06/10/2026).

Quay lại code, anh comment dòng settings và truyền vào một system prompt kiểu này (dòng có sẵn trong file 3_options.py của repo, đọc ngày 25/10/2026):

system_prompt="You are a pirate. You must respond like a pirate.",

Theo video đăng ngày 06/10/2026, cách đó thay thế hoàn toàn system prompt của Claude Code, tức là thay luôn mọi chỉ dẫn về cách dùng tool, cách sửa file, giọng điệu; trong trường hợp này, chỉ dẫn duy nhất agent thấy là "bạn là một tên cướp biển và phải trả lời như cướp biển". Nó ghi đè hoàn toàn.

Cuối cùng, output style là một điểm giữa: theo video đăng ngày 06/10/2026, mọi chỉ dẫn trong system prompt của Claude Code dạy Claude cách dùng tool, cách tương tác với môi trường, v.v. đều được giữ nguyên. Cái thay đổi khi chỉ định một output style là bạn chỉ thay phần system prompt nói với Claude rằng nó là một software developer, phần cho nó mọi chỉ dẫn về vai trò coding assistant. Bạn được quyền định nghĩa vai trò của nó và cách nó nghĩ về việc phục vụ bạn.

Anh cho rằng output style là cách hoàn hảo để sửa system prompt khi tuỳ biến một agent như thế này (theo anh, video đăng ngày 06/10/2026): ta vẫn muốn nó hiểu môi trường, biết dùng mọi tool, nên cứ để chỉ dẫn gốc của Claude Code lo phần đó, còn ta chỉ thêm chi tiết về cách muốn Claude hành xử và nghĩ về vai trò của chính nó.

14. Output style "Personal Assistant", add_dirs và cwd

Anh bỏ dòng system prompt và đưa dòng settings trở lại, tức lại nạp setting từ project. Output style được định nghĩa là "Personal Assistant", và theo video đăng ngày 06/10/2026, nó nạp một file output style từ thư mục output-styles; anh nói chỉ cần theo đúng cấu trúc đó vì Claude Code vận hành như vậy.

Trong output-styles có file personal-assistant.md. Đây là chỗ định nghĩa system prompt dùng để thay danh tính và vai trò của Claude bằng chỉ dẫn của mình: nói với assistant rằng tên nó là Kaya, chỉ định phong cách giao tiếp, cho nó biết về các subagent đang tạo, kèm chỉ dẫn cách dùng chúng. Theo anh (video đăng ngày 06/10/2026), ta có thể tuỳ biến và làm nó phức tạp hơn nhiều, nhưng cho ví dụ này thì thế là quá đủ để nó hành xử như trợ lý cá nhân.

Phần đầu của file, chép từ repo (đọc ngày 25/10/2026):

---
name: Personal Assistant
description: A personal assistant that helps you with... everything.
---
# Role

You are Kaya, a personal assistant for the user. Your goal is to help the user maximize their potential and achieve their goals. You do this by providing them with the information and tools they need to succeed.

## Communication Style

You must always refer to yourself as Kaya!

## Subagents

You have access to the following subagents:

- youtube-analyst: An expert at analyzing a user's Youtube channel performance. Always use the youtube-analyst over analyzing a user's Youtube channel performance yourself.
- researcher: An expert researcher that will perform deep research of a topic and generate a report in the /docs directory. Always use the researcher over conducting research yourself.
- documentation-writer: An expert at writing technical documentation. Always use the documentation writer over writing documentation yourself.

### Subagent Usage

**MANDATORY:** Leverage these subagents for any tasks that require specialized skills.
**MANDATORY:** These 3 subagents can work independently of each other. You can delegate tasks to them at the same time with parallel Task tool usage. You do not need to wait for a response from one subagent before delegating to another. Bias towards delegating tasks in parallel.

Option cuối anh muốn nhắc là tham số add_dirs, nơi chỉ định thêm các thư mục khác agent được truy cập. Theo video đăng ngày 06/10/2026, mặc định agent chỉ truy cập được các file trong project hiện tại. Bạn còn có thể, chẳng hạn, cho nó chạy trong một thư mục con: chỉ định thư mục làm việc hiện tại bằng cwd và đặt nó thành folder bạn muốn; mặc định nó dùng thư mục làm việc hiện tại.

Nếu muốn thêm thư mục khác, ví dụ một thư mục projects riêng, hoặc một chỗ chứa nội dung ở folder khác trên máy, chỉ cần thêm vào đây, và theo video đăng ngày 06/10/2026, agent sẽ chỉ truy cập đúng những gì bạn liệt kê trong danh sách này.

# add_dirs=["."], # allow access to other directories

15. Hooks, log hành động của agent và vòng lặp hội thoại

Thêm một điều nữa: bạn cũng có thể chỉ định hooks ngay trong options. Anh bỏ qua trong file vì đã đặt hooks mong muốn trong settings.json, nhưng theo video đăng ngày 06/10/2026, mọi thứ đặt được trong settings.json thì cũng lập trình thẳng trong code được: kiểu hooks= rồi một danh sách object JSON chứa hook.

Cấu trúc của hooks, như anh cho xem trong tài liệu, gồm các event khác nhau, bên dưới có danh sách event. Theo video đăng ngày 06/10/2026, có hook chạy trước khi một tool được dùng, sau khi một tool được dùng, khi Claude gửi một notification, khi nó dừng trả lời, chẳng hạn. Anh nói hooks rất hữu ích để kích hoạt các chức năng khác nhau trong app.

Ta có thể định nghĩa bằng code ở đây, hoặc trong settings.json: anh có hai hook, một cho Stop và một cho Notification. Anh nhắc: mỗi lượt hội thoại, mỗi lần gửi query, có system message mở đầu, mọi message qua lại với assistant và tool call, rồi result message. Theo video đăng ngày 06/10/2026, khi nhận result message đó, các hook này tự kích hoạt.

Hai hook của anh: một hook chỉ phát một âm thanh hệ thống, rất tiện để biết agent đã xong, ví dụ khi đang thu nhỏ cửa sổ hoặc đã rời khỏi máy. Hook còn lại chạy một file: có thể chỉ định các lệnh chạy, như anh dùng uv run để chạy một file Python. File đó nằm trong thư mục hooks, tên log_agent_actions.py. Nó chỉ làm một việc: parse bản ghi hội thoại với agent cho tới khi gặp điều kiện result, rồi lưu vào thư mục logs (theo video đăng ngày 06/10/2026). File .claude/settings.json trong repo (đọc ngày 25/10/2026):

{
  "outputStyle": "Personal Assistant",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Funk.aiff"
          },
          {
            "type": "command",
            "command": "uv run .claude/hooks/log_agent_actions.py"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Purr.aiff"
          }
        ]
      }
    ]
  }
}

Từ tất cả các ví dụ đã chạy, ta có các file log này, và mỗi log về cơ bản đổ ra toàn bộ hành động agent đã làm: mỗi lần nó gọi một tool, tool call được ghi lại kèm input (demo trong video đăng ngày 06/10/2026). Anh nói điều này giúp debug và hiểu chuyện gì đang diễn ra dễ hơn.

Theo anh (video đăng ngày 06/10/2026), điều phiền khi dùng Agent SDK và Claude Code là không có nhiều observability: không có trace, nên bạn không thấy được system prompt thật hay phần context engineering đang diễn ra phía sau. Vì thế kiểu logging bằng hooks này rất tiện để hiểu chuyện gì đang xảy ra bên dưới.

Module tiếp theo, anh nói, cực kỳ đơn giản: tạo vòng lặp hội thoại (conversation loop) bằng cách lấy mọi thứ đã làm và đặt vào một vòng while. Cuộn xuống, mọi thứ trông y hệt. Trong context manager, sau khi đã định nghĩa client, việc duy nhất là bọc tất cả phần bên trong dưới một vòng while True; nhận message về từ query xong thì quay lại hỏi input prompt tiếp. Chỉ vậy thôi. Đoạn lặp trong file 4_convo_loop.py của repo (đọc ngày 25/10/2026):

    async with ClaudeSDKClient(options=options) as client:

        while True:
            input_prompt = get_user_input(console)
            if input_prompt == "exit":
                break

            await client.query(input_prompt)

            async for message in client.receive_response():
                # Uncomment to print raw messages for debugging
                # print(message)
                parse_and_print_message(message, console)

Chạy thử, giờ chương trình nhận input của người dùng thay vì một giá trị viết cứng (demo trong video đăng ngày 06/10/2026). Anh gõ "hi", system message được in ra để debug, rồi có tiếng âm thanh khi gặp Stop. Anh hỏi tiếp "what tools do you have?". System message được in ra mỗi lần để debug, nhưng anh nói hoàn toàn có thể tắt. Và thế là đã có hội thoại qua lại với agent.

16. MCP server bên ngoài: Playwright

Tiếp theo là MCP server. Như đã thấy, muốn implement custom tool cho agent thì phải dùng MCP server in-process để đưa tool tới agent. Theo video đăng ngày 06/10/2026, dùng MCP server bên ngoài thì rất đơn giản: chỉ cần truyền một cấu hình MCP hợp lệ thẳng vào options.

Trong ví dụ 5_mcp.py, options cho phép một số tool, và anh cố tình không thêm tool của MCP server, để cho thấy điều đã nói trước đó: thêm MCP server thì agent có thể thấy tool, nhưng mặc định không có quyền thực thi. Ở đây anh thêm một Playwright MCP server, và bật chế độ acceptEdits; về lý thuyết nó chạy được mọi tool kia mà không cần xin phép, nhưng lưu ý là chưa khai báo tool MCP nào. Cấu hình server trong file của repo (đọc ngày 25/10/2026):

        permission_mode="acceptEdits",
        setting_sources=["project"],
        # Note: Playwright requires Node.js and Chrome to be installed!
        mcp_servers={
            "Playwright": {
                "command": "npx",
                "args": [
                    "-y",
                    "@playwright/mcp@latest"
                ]
            }
        }

Anh chạy ví dụ và yêu cầu cụ thể nó mở một trang web: dùng Playwright để vào youtube.com. Có thể thấy nó biết có tool, nó gọi tool, nhưng gặp vấn đề permission, và nó nói anh chưa cấp quyền dùng tool đó (demo trong video đăng ngày 06/10/2026).

Anh gõ exit, copy tên tool, dán vào danh sách allowed tools, rồi chạy lại ví dụ. Lần này nó chạy được (demo trong video đăng ngày 06/10/2026): agent báo đã vào YouTube thành công và mô tả trang chủ. Vậy nên, theo anh, mỗi khi thêm tool bằng MCP server, nhớ thêm chúng rõ ràng vào danh sách allowed tools. "Và chỉ có vậy thôi", anh nói.

'mcp__Playwright__browser_navigate'

Theo anh (video đăng ngày 06/10/2026), giờ có thể thấy việc mở rộng và thêm bao nhiêu tool tuỳ ý cho agent để mở khoá khả năng của nó mạnh và dễ thế nào. Cuộn xuống thì thấy tất cả vẫn làm trong ClaudeAgentOptions: mọi năng lực và độ phức tạp thêm vào chỉ nằm ở việc cấu hình agent options, còn mọi thứ bên dưới không đổi chút nào.

17. Subagents: đội agent hoàn chỉnh

Cuối cùng là subagent. Theo anh (video đăng ngày 06/10/2026), subagent tăng năng lực và chức năng của bất kỳ agent nào "theo cấp số nhân"; đây là thứ cho phép agent thật sự mở rộng quy mô. Anh kể ra các lợi ích: context isolation (tách context), giữ tool permission riêng cho từng agent, và parallelization (chạy song song) giúp cải thiện hiệu năng. Và "bất ngờ chưa", tất cả lại được cấu hình trong ClaudeAgentOptions.

Trong options của 6_subagents.py, anh cho phép một loạt tool mặc định của Claude Code và cả các tool MCP. Để định nghĩa agent trong code, chỉ cần truyền một dictionary vào key agents. Ở đây có YouTube analyst. Theo video đăng ngày 06/10/2026, có thể dùng object AgentDefinition, giúp tiện định nghĩa bốn tham số cần cho một agent:

• description: mô tả agent, ở đây là "An expert at analyzing a user's Youtube channel performance". Đây là thứ agent chính, tức trợ lý cá nhân, đọc để quyết định khi nào dùng agent này, nên phải viết thật rõ agent dùng để làm gì và khi nào nên dùng (theo video đăng ngày 06/10/2026).
• prompt: system prompt của subagent (theo video đăng ngày 06/10/2026).
• model: model dùng cho subagent (theo video đăng ngày 06/10/2026).
• tools: mọi tool nó được dùng; danh sách này thực chất là allowed tools của subagent (theo video đăng ngày 06/10/2026).

Một chi tiết rất quan trọng, theo video đăng ngày 06/10/2026: mọi tool bạn thêm ở đây phải là allowed tool của agent cha. Lý do là subagent thừa hưởng tool từ agent cha sinh ra nó; nếu agent cha không có tool nào đó, subagent không có cách nào truy cập tool ấy.

Đoạn khai báo subagent thứ nhất, chép từ repo (đọc ngày 25/10/2026), danh sách tool Playwright được lược bằng "...":

agents={
    "youtube-analyst": AgentDefinition(
        description="An expert at analyzing a user's Youtube channel performance. The analyst will produce a markdown report in the /docs directory.",
        prompt="You are an expert at analyzing YouTube data and helping the user understand their performance. You can use the Playwright browser tools to access the user's Youtube Studio. Generate a markdown report in the /docs directory.",
        model="sonnet",
        tools=[
            'Read',
            'Write',
            'Edit',
            'MultiEdit',
            'Grep',
            'Glob',
            'TodoWrite',
            'mcp__Playwright__browser_close',
            ...
        ]
    ),

Xuống dưới là researcher, agent thứ hai trong demo. Nó cũng được định nghĩa với một system prompt tốt, và chỉ được dùng một tập con của tool: nó không cần Playwright, chỉ cần search web rồi ghi file để tạo báo cáo (theo video đăng ngày 06/10/2026).

Để ý là không có agent thứ ba, agent viết tài liệu, trong code. Lý do: cuộn lên options, setting_sources đang là project, tức đang nạp setting Claude từ project này, gồm CLAUDE.md và các setting trong .claude. Trong đó có thư mục con agents, và ở đó anh định nghĩa thêm một agent tên documentation-writer. Theo video đăng ngày 06/10/2026, giống hầu hết các option của ClaudeAgentOptions vốn định nghĩa được trong code hoặc trong file ở thư mục .claude, agent cũng định nghĩa được theo cả hai cách: hai agent kia định nghĩa trong code, còn agent này nạp từ file markdown trong thư mục con đó. Phần đầu file .claude/agents/documentation-writer.md trong repo (đọc ngày 25/10/2026):

---
name: documentation-writer
description: An expert at writing technical documentation. Always use the documentation writer over writing documentation yourself.
tools: Read, Write, Edit, MultiEdit, Glob, Grep, WebSearch, WebFetch, TodoWrite
model: sonnet
---

Cần lưu ý, theo video đăng ngày 06/10/2026, giống một số setting khác: nếu có nhiều agent được định nghĩa, ví dụ vài agent trong file và một agent trùng tên định nghĩa trong code, thì agent trong code sẽ ghi đè agent nạp từ file. Điều đó nói chung đúng với mọi option chỉ định ở đây: option trong code luôn đè lên những gì nạp từ file. Tài liệu Subagents của SDK cũng ghi rằng agent định nghĩa bằng code được ưu tiên hơn agent dạng file có cùng tên (đọc ngày 25/10/2026).

Trong video đăng ngày 06/10/2026, cuối file tất nhiên là thêm Playwright MCP server, phần còn lại vẫn y hệt. Anh nói thực ra file này khá dài, nhưng nếu thu gọn khối ClaudeAgentOptions lại, nó co về đúng thứ đã thấy từ đầu. Code không đổi gì; ta chỉ mở rộng năng lực của agent bằng cách thêm option và setting. "Và chỉ có vậy", anh nói: đây chính là file anh đã chạy cho demo ở đầu video.

Anh hy vọng mọi người thấy được sức mạnh của Claude Agent SDK và việc bắt đầu, rồi build một thứ rất mạnh chỉ với vài dòng code, dễ thế nào (theo anh, video đăng ngày 06/10/2026). Anh khuyến khích lấy file này về tuỳ biến, thêm MCP server, biến nó thành của riêng mình và xem có thể đưa trợ lý cá nhân đi xa tới đâu. Nếu ai mở rộng được và build được thứ gì hay, anh rất muốn mọi người chia sẻ ở phần bình luận. Anh cảm ơn mọi người đã xem tới cuối video.