Cách tạo và sử dụng Subagents trong Claude Code— hướng dẫn thực tế

CometAPI
AnnaOct 22, 2025
Cách tạo và sử dụng Subagents trong Claude Code— hướng dẫn thực tế

Subagents là một trong những bổ sung hữu ích nhất cho hệ sinh thái Claude Code / Claude Agent: chúng cho phép bạn chia nhỏ quy trình làm việc phức tạp thành các "đồng đội" AI chuyên biệt, bảo toàn ngữ cảnh luồng chính và giới hạn quyền truy cập công cụ một cách an toàn. Bài viết này giải thích các tác nhân phụ là gì, làm thế nào để tạo ra và gọi chúng (CLI, hệ thống tập tin và SDK), nguyên tắc thiết kế bạn nên tuân theo khi xây dựng chúng, và mã mẫu bê tông bạn có thể sao chép và điều chỉnh.

Đại lý phụ là gì?

A đại lý phụ là một trợ lý AI được cấu hình sẵn, có phạm vi hẹp mà Claude Code (hoặc Claude Agent SDK) có thể phân công công việc. Mỗi tác nhân phụ:

  • Có tên riêng và mô tả mục đích rõ ràng.
  • Chạy trong nó cửa sổ ngữ cảnh riêng tách biệt khỏi cuộc trò chuyện chính (để những chuỗi chi tiết dài không làm ảnh hưởng đến bối cảnh của người điều phối).
  • Có thể được cấu hình với một tập hợp giới hạn công cụ (đọc/ghi tệp, bash, grep, công cụ MCP, v.v.) và với lựa chọn mô hình cụ thể.
  • Chứa lời nhắc hệ thống (tính cách và hướng dẫn của tác nhân phụ) hướng dẫn hành vi và các ràng buộc.

Những đặc tính này làm cho các tác nhân phụ trở nên lý tưởng cho các tác vụ đòi hỏi nhiều mã thông báo (nghiên cứu, tìm kiếm nhật ký lớn), nhạy cảm với bảo mật (quét hoặc các công cụ có khả năng phá hoại) hoặc lặp đi lặp lại và được chỉ định rõ ràng (kiểm tra kiểu, chạy thử nghiệm).

Anthropic đã lặp lại nhanh chóng: Claude Code CLI và Agent SDK đã được tái cấu trúc và mở rộng thành SDK của Claude Agent, hỗ trợ plugin đã được giới thiệu để đóng gói các tác nhân và các tùy chỉnh liên quan (lệnh gạch chéo, máy chủ MCP, móc) và Kỹ năng cung cấp một cách để đóng gói các quy trình làm việc của miền để tái sử dụng trên Claude.ai, Claude Code và Agent SDK. Những cập nhật này giúp dễ dàng hơn chia sẻ, cài đặt và phiên bản các tác nhân phụ trên khắp các nhóm và dự án. Nếu bạn dự định xây dựng quy trình làm việc sản xuất, bạn nên đánh giá gói plugin/kỹ năng và các mô hình triển khai dựa trên SDK.

Tại sao các đại lý phụ lại quan trọng

Ba lý do khiến chúng hữu ích ngay lập tức:

  1. Bảo toàn bối cảnh — các tìm kiếm, chạy thử hoặc quét dài hoặc nhiễu được thực hiện bên trong một tác nhân phụ thay vì làm quá tải ngữ cảnh chính. Điều này giúp giảm thiểu lãng phí mã thông báo và giúp việc suy luận kết quả dễ dàng hơn.
  2. Chuyên môn chuyên sâu — bạn có thể mã hóa kiến ​​thức và hành vi của miền trong một lời nhắc hệ thống được thiết kế riêng cho nhiệm vụ (ví dụ: security-auditor tập trung vào các vấn đề bí mật, sự phụ thuộc và sử dụng shell không an toàn).
  3. Quyền an toàn hơn — giới hạn các công cụ cho mỗi tác nhân phụ làm giảm bán kính nổ (người đánh giá tài liệu có thể có các công cụ chỉ đọc; người chạy thử nghiệm có Bash nhưng không Edit).
  4. song song hóa: Bạn có thể khởi chạy nhiều tác nhân phụ để chạy đồng thời (ví dụ: style-checker, security-scanner, test-runner) và sau đó thu thập kết quả ngắn gọn của họ — một chiến thắng lớn cho các cuộc kiểm tra độc lập, tốn kém.

Điều kiện tiên quyết để sử dụng Subagents trong Claude Code

Trước khi bắt đầu xây dựng Subagents, hãy đảm bảo bạn đã có những điều sau:

1) Mã Claude đã được cài đặt và xác thực

Cài đặt Claude Code CLI hoặc sử dụng tích hợp web/IDE. Tài liệu hướng dẫn cài đặt và khởi động nhanh của CometAPI liệt kê các phương pháp cài đặt được hỗ trợ (gói toàn cầu npm hoặc trình cài đặt gốc) và chỉ ra cách xác minh cài đặt của bạn bằng claude --version / claude doctor. Bạn cũng sẽ cần một Sao chổiAPI tài khoản (Sử dụng khóa CometAPI để truy cập mã Claude rẻ hơn và thuận tiện hơn so với mô hình chính thức.) như đã lưu ý trong phần Bắt đầu nhanh.

2) Node/môi trường (cho một số đường dẫn cài đặt) và công cụ shell cơ bản

Nếu bạn cài đặt qua gói npm, bạn nên có Node.js (Node 18+ là phổ biến trong các ví dụ). Nếu bạn định sử dụng Agent SDK (JavaScript/TypeScript hoặc Python), bạn sẽ cần một dự án đã cài đặt sẵn SDK. Nhiều hướng dẫn sử dụng các công cụ phát triển tiêu chuẩn (git, bash, tùy chọn). gh CLI cho quy trình làm việc của GitHub).

3) Bố cục dự án & CLAUDE.md

Thực hành tốt nhất là giữ lại các tài liệu trợ giúp cấp kho lưu trữ (CLAUDE.md) và đưa các tác nhân có phạm vi dự án vào .claude/agents/ để các đồng đội kế thừa chúng. Các tệp CLAUDE.md được tự động đưa vào ngữ cảnh của Claude và giúp hướng dẫn hành vi nhất quán trong các phiên, mỗi tác nhân phụ là một tệp Markdown với phần đầu YAML. Ví dụ tối giản:

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.

Return results in JSON with fields: summary, issues.
  • name là một định danh chữ thường.
  • description hướng dẫn tự động gọi và khớp lệnh.
  • tools hạn chế quyền truy cập công cụ (bỏ qua việc kế thừa mọi thứ).
  • model có thể sonnet, opus, haiku, hoặc là inherit.

4) Quyền và máy chủ MCP (tùy chọn nhưng phổ biến)

Nếu quy trình làm việc của bạn sử dụng máy chủ Giao thức Bối cảnh Mô hình (MCP) hoặc các công cụ bên ngoài (Puppeteer, Sentry, các công cụ REST tùy chỉnh), hãy đảm bảo máy chủ MCP của bạn được cấu hình và có thể truy cập được. Đối với các hoạt động nhạy cảm (write, bash, git commit), hãy cân nhắc kỹ về danh sách cho phép và giới hạn cho từng tác nhân. tools phạm vi.

Cách tạo Subagents trong Claude Code

Bạn có thể tạo các tác nhân phụ theo ba cách chính: thông qua CLI tương tác (/agents), dưới dạng tệp markdown hệ thống tệp, hoặc theo chương trình thông qua Agent SDK. Dưới đây là các tùy chọn từng bước:

Claude Code hỗ trợ ba cách thực tế để tạo tác nhân phụ:

  1. CLI tương tác /agents UI — nhanh nhất để tạo lặp lại trong một phiên.
  2. Dựa trên hệ thống tập tin — tạo các tệp Markdown với frontmatter YAML trong .claude/agents/ (cấp độ dự án) hoặc ~/.claude/agents/ (cấp độ người dùng). Các tác nhân dự án có mức độ ưu tiên cao hơn.
  3. Lập trình (SDK đại lý) — định nghĩa các tác nhân phụ trong mã thông qua agents tham số khi bạn gọi query(); được khuyến nghị cho các ứng dụng chạy trên SDK. Cách tiếp cận này lý tưởng khi các tác nhân phụ phải được tạo động hoặc nhúng vào ứng dụng.

Luồng tương tác nhanh (bước đầu tiên được đề xuất)

  1. Khởi động Claude Code trong terminal của bạn hoặc mở bảng lệnh trong VS Code.
  2. Chạy giao diện subagents bằng lệnh slash:
/agents
  1. Chọn Tạo tác nhân mới, chọn phạm vi cấp dự án hoặc cấp người dùng, điền vào dấu nhắc tên/mô tả/công cụ/hệ thống và lưu. Bạn có thể tạo bản nháp với Claude và sau đó tinh chỉnh nó. Sau khi lưu, tác nhân sẽ có sẵn trong /agents và có thể được gọi một cách rõ ràng hoặc tự động.

Các tác nhân phụ dựa trên hệ thống tập tin (Markdown + YAML frontmatter)

Các tác nhân phụ được lưu trữ dưới dạng tệp Markdown với phần mở đầu YAML. Đặt chúng vào:

  • Phạm vi dự án: .claude/agents/*.md (ưu tiên cao nhất)
  • Phạm vi người dùng: ~/.claude/agents/*.md

Cấu trúc tập tin cơ bản:

---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash  # optional; omit to inherit

model: sonnet  # optional; or 'inherit'

---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet

Một số lưu ý khi thực hiện:

  • name phải viết thường và có dấu gạch ngang.
  • Bỏ sót tools sẽ cho phép tác nhân phụ kế thừa tất cả các công cụ của luồng chính; liệt kê rõ ràng các công cụ sẽ áp dụng mô hình đặc quyền tối thiểu.
  • Sử dụng model: 'inherit' để có hành vi nhất quán với luồng chính hoặc chỉ định một bí danh mô hình (ví dụ: sonnet, opus, haiku).

Định nghĩa JSON của CLI (sử dụng tùy ý/phiên)

Bạn có thể xác định các tác nhân phụ tạm thời trực tuyến khi khởi chạy phiên:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer. Focus on security and best practices.",
    "tools": ,
    "model": "sonnet"
  }
}'

Các tác nhân do CLI xác định hữu ích cho các lần chạy theo kịch bản hoặc thử nghiệm; chúng có mức độ ưu tiên thấp hơn các tác nhân dự án nhưng cao hơn các tác nhân người dùng.

Định nghĩa theo chương trình (SDK tác nhân — được khuyến nghị cho ứng dụng)

Nếu bạn đang xây dựng một ứng dụng hoặc tự động hóa, hãy xác định các tác nhân phụ theo chương trình thông qua SDK của tác nhân agents tham số (đây là tùy chọn tích hợp nhất). Ví dụ (TypeScript):

import { query } from '@anthropic-ai/claude-agent-sdk';

async function runReview() {
  const result = await query({
    prompt: "Assess the authentication module for security issues",
    options: {
      agents: {
        "code-reviewer": {
          description: "Expert code review specialist",
          prompt: `You are a code review specialist...`,
          tools: ,
          model: "sonnet"
        },
        "test-runner": {
          description: "Runs the test suite and analyzes failures",
          prompt: `You run tests and summarize failures...`,
          tools: ,
          model: "sonnet"
        }
      }
    }
  });

  console.log(result);
}

SDK cũng chấp nhận các tác nhân dựa trên hệ thống tập tin (nó sẽ tải .claude/agents/ tệp) nếu bạn thích mẫu đó. Các tác nhân lập trình mạnh mẽ cho quy trình làm việc năng động và tích hợp CI.

Đối với Python, claude-agent-sdk gói hỗ trợ các mẫu tương tự: bạn có thể sử dụng query() or ClaudeSDKClient và cấu hình các tùy chọn, công cụ và máy chủ MCP theo chương trình. Xem kho lưu trữ Python SDK để biết các ví dụ bắt đầu nhanh.


Làm thế nào để triệu hồi các tác nhân phụ

Ủy quyền tự động

Claude Code có thể tự động Chọn một tác nhân phụ khi lời nhắc của người dùng khớp với mục đích của tác nhân phụ đó. Điều này hữu ích cho việc điều phối nền tảng, trong đó tác nhân chính tự động chuyển hướng nhiệm vụ đến đúng chuyên gia. Hãy dựa vào mô tả tác nhân phụ rõ ràng và lời nhắc hệ thống tập trung để cải thiện độ chính xác của lựa chọn tự động.

Lời kêu gọi rõ ràng (khuyến khích để rõ ràng hơn)

Bạn có thể gọi rõ ràng một tác nhân trong cuộc trò chuyện:

> Use the code-reviewer subagent to check my recent changes

Việc gọi rõ ràng mang tính quyết định và được khuyến nghị cho các luồng sản xuất khi bạn muốn tránh việc phân quyền không mong muốn.

Các mẫu điều phối SDK

Các mẫu phổ biến trong ứng dụng SDK:

  • Nĩa + thu thập: Khởi chạy nhiều tác nhân phụ song song, thu thập câu trả lời ngắn gọn của từng tác nhân, sau đó tóm tắt/hợp nhất kết quả trong tác nhân chính.
  • Vòng lặp giám sát: Người điều phối phân công nhiệm vụ cho các tác nhân phụ, kiểm tra kết quả và chấp nhận hoặc yêu cầu tính toán lại/làm rõ.
  • Thực thi hộp cát: Cung cấp các khả năng có khả năng gây nguy hiểm (triển khai, chạy tập lệnh) cho một tác nhân bị hạn chế chặt chẽ và yêu cầu sự chấp thuận rõ ràng của con người trước khi thực thi.

Các mẫu này tương ứng với các triển khai thực tế bằng cách sử dụng công cụ quản lý phiên, móc và MCP của Agent SDK.


Làm thế nào để tạo ra các tác nhân phụ hữu ích, an toàn và có thể cấu thành

1) Trách nhiệm duy nhất và lời nhắc rõ ràng

Mỗi tác nhân phụ cần có một mục đích rõ ràng và một lời nhắc hệ thống nêu rõ ranh giới, tiêu chí thành công và định dạng đầu ra. Nếu đầu ra mong muốn được cấu trúc (JSON, danh sách bullet, bản vá mã), hãy hướng dẫn tác nhân phụ một cách chính xác để giảm lỗi phân tích cú pháp.

2) Quyền tối thiểu đối với các công cụ

Chỉ cấp các công cụ mà một đại lý phụ cần. Ví dụ, một người đánh giá tài liệu không cần Write or Bash. Đặt chế độ chỉ đọc khi có thể và tăng cường quyền công cụ một cách rõ ràng khi cần. Điều này giúp giảm thiểu rủi ro và đơn giản hóa việc kiểm tra.

3) Trả về các đầu ra có cấu trúc, nhỏ gọn

Các đại lý phụ nên quay trở lại câu trả lời ngắn gọn, cuối cùng thay vì những dấu vết suy nghĩ dài dòng. Một mô hình phổ biến là: thực hiện các tác vụ nặng trong ngữ cảnh của tác nhân phụ, sau đó trả về một bản tóm tắt ngắn gọn kèm theo các tệp đính kèm (bản vá, tham chiếu tệp, JSON). Điều này tối đa hóa hiệu quả ngữ cảnh cho trình điều phối.

4) Khả năng kiểm tra và quản lý phiên bản

Lưu trữ các tệp subagent trong kiểm soát phiên bản, tạo các bài kiểm tra CI thực hiện các lần chạy thực tế với các đầu vào nhỏ và ghim các mô hình/bộ công cụ. Nếu bạn dựa vào Kỹ năng và plugin, hãy áp dụng các mẫu thị trường plugin/phiên bản để quản lý việc nâng cấp và khôi phục.

5) Kiểm toán móc và điểm kiểm tra vòng lặp của con người

Sử dụng các hook SDK để chặn các lệnh gọi công cụ (hook PreToolUse) và yêu cầu sự chấp thuận của con người đối với các hành động phá hoại. Ghi lại tất cả các lệnh gọi công cụ để kiểm tra lại. SDK cung cấp các hook và cơ chế cấp phép để hỗ trợ mô hình này.

Mẫu ứng dụng — một đường ống nhỏ, giống như sản xuất

Dưới đây là một ví dụ ngắn gọn cho thấy các thành phần điển hình: một tác nhân hệ thống tệp, một lệnh gọi SDK sử dụng hai tác nhân (một để xem xét, một để kiểm tra) và một quá trình phối hợp đơn giản.

1) Tác nhân hệ thống tập tin: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
  "summary": "one-line summary",
  "issues": ,
  "recommended_changes": 
}

2) Phối hợp theo chương trình (Node.js)

import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';

async function runPipeline() {
  const result = query({
    prompt: 'Run PR checks: security review then unit tests.',
    options: {
      agents: {
        'code-reviewer': {
          description: 'Use PROACTIVELY after code changes; output JSON with issues.',
          prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
          tools: ,
          model: 'sonnet'
        },
        'test-runner': {
          description: 'Run test suite and summarize failing tests.',
          prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
          tools: 
        }
      }
    }
  });

  for await (const message of result) {
    // Implement streaming logic: messages may include subagent outputs
    console.log(message);
  }
}

runPipeline().catch(console.error);

Ghi chú: các code-reviewer được lưu trữ trong kho lưu trữ để nhóm có thể tái sử dụng; lệnh gọi SDK chứng minh các tác nhân lập trình được ưu tiên và tools phạm vi ngăn chặn việc ghi ngẫu nhiên.


Các chủ đề và mẫu nâng cao

Cấu hình tác nhân động

Tạo các nhà máy tác nhân có tham số để chọn mô hình và bộ công cụ tùy thuộc vào môi trường (dev so với prod) hoặc mức độ nghiêm trọng (ví dụ: strict vs balanced Các ví dụ SDK cho thấy cách tạo định nghĩa tác nhân khi chạy.

Song song hóa

Tách nhiều tác nhân phân tích chỉ đọc song song (kiểu dáng, bảo mật, phạm vi kiểm tra) và tổng hợp đầu ra JSON của chúng trong luồng chính. Điều này giúp giảm đáng kể thời gian xử lý cho các kho lưu trữ lớn.

Các tác nhân được cung cấp bởi plugin

Các plugin có thể cung cấp các tác nhân phụ được đóng gói cùng với bản kê khai plugin; chúng xuất hiện trong /agents cùng với các tác nhân tùy chỉnh và có thể được gọi một cách rõ ràng. Sử dụng tính năng này để phân phối các tác nhân được chuẩn hóa cho các nhóm.

Nơi sử dụng mã Claude cli được khuyến nghị nhiều nhất

Chúng tôi rất vui mừng khi thông báo rằng CometAPI hiện hỗ trợ đầy đủ lệnh Claude Code mạnh mẽ. Bạn chỉ cần cài đặt Claude Code và xác thực bằng khóa API Comet và địa chỉ cơ sở đã lấy được để sử dụng mô hình API Comet trên Claude Code.

Tại sao nên sử dụng claude code thông qua CometAPI?

Các tính năng hàng đầu của Trí tuệ nhân tạo: Dễ dàng tạo, gỡ lỗi và tối ưu hóa mã bằng các mô hình được xây dựng riêng cho nhà phát triển.

  • Lựa chọn mô hình linh hoạt: Dòng mô hình toàn diện của chúng tôi cho phép bạn phát triển liền mạch hơn.
  • Tích hợp liền mạch: API luôn khả dụng. Tích hợp Claude Code trực tiếp vào quy trình làm việc hiện tại của bạn chỉ trong vài phút.
  • Sử dụng Claude Code thông qua CometAPI sẽ tiết kiệm nhiều chi phí hơn. API Claude do CometAPI cung cấp có giá giảm 20% so với giá chính thức và được cập nhật theo mẫu mới nhất bởi nhà cung cấp chính thức.

Sẵn sàng sử dụng Claude Code cli? tham khảo Hướng dẫn API để có hướng dẫn chi tiết.

Nếu bạn muốn biết thêm mẹo, hướng dẫn và tin tức về AI, hãy theo dõi chúng tôi trên VKX và Discord!

Xem thêm Làm thế nào để cài đặt và chạy Claude Code thông qua CometAPI?

Lời cuối

Xử lý các tác nhân phụ như các micro-personas có phiên bản, có thể tái sử dụng. Bắt đầu nhỏ: tạo một doc-reviewertest-runner đối với một kho lưu trữ, hãy kiểm tra chúng .claude/agents/và tự động hóa chúng trong CI bằng cách sử dụng headless claude -p. Lặp lại lời nhắc, thêm đầu ra có cấu trúc và thắt chặt quyền công cụ.

Mô hình tư duy hữu ích nhất: hãy tưởng tượng Claude là một quản lý dự án và các cộng sự là chuyên gia trong nhóm. Quản lý phân công nhiệm vụ rõ ràng, tổng hợp kết quả của các chuyên gia và viết báo cáo cuối cùng. Theo thời gian, bạn sẽ thấy sự cải thiện về độ tin cậy, khả năng kiểm thử và khả năng tự động hóa khối lượng lớn quy trình làm việc của nhà phát triển.

Đọc thêm

500+ Mô hình trong Một API

Giảm giá lên đến 20%