Research Agent một dòng code — Bắt đầu với Claude Agent SDK

Research agent là một trong những ứng dụng mạnh nhất của AI agents. Thay vì theo workflow cố định, agent tự quyết định tìm gì tiếp theo dựa trên những gì đã khám phá. Bài này hướng dẫn bạn xây dựng research agent từ prototype đến production-ready với Claude Agent SDK.

Bài viết dựa trên Claude Cookbooks chính thức của Anthropic.

Tại sao Research Agent?

Research là use case lý tưởng cho agents vì hai lý do:

1. Thông tin không self-contained — Câu hỏi đầu vào không chứa đáp án. Agent phải tương tác với hệ thống bên ngoài (search engines, databases, APIs) để thu thập dữ liệu.
2. Lộ trình khám phá xuất hiện trong quá trình — Không thể predetermine workflow. Việc agent nên tìm tài chính hay pháp lý phụ thuộc vào những gì nó phát hiện về business model.

Ứng dụng thực tế: phân tích cạnh tranh, troubleshooting kỹ thuật, nghiên cứu đầu tư, literature review.

Agent đầu tiên: Stateless Query

Đơn giản nhất — chỉ vài dòng code:

from claude_agent_sdk import query

result = await query(
    prompt="Phân tích thị trường AI tại Việt Nam 2026",
    allowed_tools=["WebSearch"],
    model="claude-sonnet-4-6"
)

print(result.result)

Cách hoạt động

• query() tạo một agent interaction stateless (không conversation memory)
• allowed_tools=["WebSearch"] cho phép Claude tự do search web
• Agent tự quyết định: search gì, bao nhiêu lần, synthesize kết quả ra sao

Tool permissions

Khi nào dùng stateless query?

• Câu hỏi research one-off, không cần context trước đó
• Xử lý song song nhiều câu hỏi độc lập
• Cần fresh context cho mỗi query

Nâng cấp: 3 cải tiến quan trọng

1. Conversation Memory với ClaudeSDKClient

Stateless queries không thể xây dựng trên kết quả trước. Ví dụ: "Tìm top AI startups" rồi "Họ được fund thế nào?" — câu thứ hai không biết startups nào.

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-6",
    allowed_tools=["WebSearch", "Read"]
)

async with ClaudeSDKClient(options=options) as client:
    # Turn 1: Research
    await client.query("Top AI startups Việt Nam 2026?")
    async for msg in client.receive_response():
        process(msg)

    # Turn 2: Follow-up (có context từ turn 1)
    await client.query("So sánh funding của top 3")
    async for msg in client.receive_response():
        process(msg)

ClaudeSDKClient duy trì conversation history — turn 2 biết "top 3" là startups nào từ turn 1.

2. System Prompts cho specialized behavior

Research domains khác nhau cần tiêu chuẩn khác nhau. Financial analysis cần rigorous hơn tech news summaries.

options = ClaudeAgentOptions(
    model="claude-sonnet-4-6",
    system_prompt="""Bạn là research analyst chuyên thị trường Việt Nam.
    - Ưu tiên nguồn: báo cáo chính thức, số liệu thống kê
    - Trích dẫn nguồn cho mọi claim
    - Output format: executive summary + chi tiết + sources""",
    allowed_tools=["WebSearch"]
)

3. Multimodal Research với Read Tool

Research thực tế không chỉ text. Market reports có charts, technical docs có diagrams. Enable Read tool để Claude phân tích images, PDFs, và visual content.

options = ClaudeAgentOptions(
    allowed_tools=["WebSearch", "Read"],
    # Read tool cho phép Claude đọc files, images, PDFs
)

Xử lý buffer overflow

Khi làm việc với images hoặc large data, có thể gặp lỗi buffer:

Fatal error: JSON message exceeded maximum buffer size of 1048576 bytes

Giải pháp: limit kích thước responses hoặc chunk large data trước khi gửi.

Pattern áp dụng

Bước tiếp theo: Đọc Chief of Staff Agent để học cách điều phối multi-agent, hoặc Observability Agent để tích hợp với hệ thống bên ngoài qua MCP.