Cách xây dựng AI agent theo lịch trình bằng Claude Code

Claude Code hiện đã hỗ trợ các tác vụ theo lịch trình một cách tự nhiên. Hãy tìm hiểu cách thiết lập các AI agent tự động, tự phục hồi, chạy theo lịch trình mà không cần giám sát qua bài viết sau đây!

Thiết lập môi trường

Điều kiện tiên quyết

Bạn cần:

• Node.js 18+ — Claude Code chạy trên Node
• Đã cài đặt Claude Code — npm install -g @anthropic-ai/claude-code
• Một API key của Anthropic — Được lưu trữ dưới dạng ANTHROPIC_API_KEY trong môi trường của bạn
• Một hệ thống giống Unix — Linux hoặc macOS để lên lịch dựa trên cron (người dùng Windows có thể sử dụng Task Scheduler hoặc WSL)

Cài đặt

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

Kiểm tra cài đặt:

claude --version

Lưu trữ API key

Đối với các agent được lên lịch, API key cần phải có thể truy cập được trong thời gian chạy mà không cần nhập thủ công. Lưu trữ an toàn:

# For a system-level service, add to /etc/environment or a secure env file
ANTHROPIC_API_KEY="your-key-here"

# Đối với service cấp hệ thống, hãy thêm vào /etc/environment hoặc file env bảo mật
ANTHROPIC_API_KEY="key-của-bạn-ở-đây"

Đối với hệ thống sản xuất, hãy sử dụng trình quản lý secrets chuyên dụng:

• AWS Secrets Manager — Tích hợp với EC2, Lambda và ECS
• HashiCorp Vault — Hoạt động trên nhiều nhà cung cấp dịch vụ đám mây
• GitHub Actions Secrets — Nếu chạy trong các CI/CD pipeline 
• 1Password Secrets Automation — Tốt cho thiết lập nhóm

Không bao giờ hardcode key trong script hoặc đưa nó vào hệ thống kiểm soát phiên bản.

Sử dụng CLAUDE.md cho hướng dẫn agent liên tục

Một trong những tính năng hữu ích nhất của Claude Code dành cho các agent theo lịch trình là file CLAUDE.md. Đặt file này vào thư mục gốc của dự án (hoặc tại ~/.claude/CLAUDE.md để có hướng dẫn chung cho agent), và Claude sẽ đọc nó khi bắt đầu mỗi phiên.

Đây là nơi bạn định nghĩa ngữ cảnh liên tục mà agent của bạn cần để hoạt động:

# Monitoring Agent Instructions

## Project Context
This is a Node.js API server. Logs are stored in ./logs/.
The database is PostgreSQL running on localhost:5432.
The API serves traffic on ports 3000 (staging) and 4000 (production).

## Agent Responsibilities
- You are a monitoring agent. Your job is to observe and report, not to make changes.
- When you find issues, write them to ./alerts/[timestamp].json
- Never modify files in ./src/ or ./config/
- If you find a critical issue, also append a summary to ./alerts/critical.log

## What "Critical" Means
- Error rate above 5% in the last hour
- Average response time above 2000ms
- Database connection failures
- Any 5xx errors from /api/payments endpoint

## Escalation
For critical alerts, run /scripts/notify-oncall.sh with the alert details.
For warnings, append to /alerts/warnings.log only.

# Hướng dẫn cho Agent giám sát

## Bối cảnh dự án
Đây là máy chủ API Node.js. Nhật ký được lưu trữ trong ./logs/.
Cơ sở dữ liệu là PostgreSQL chạy trên localhost:5432.
API phục vụ lưu lượng truy cập trên cổng 3000 (môi trường thử nghiệm) và 4000 (môi trường sản xuất).

## Trách nhiệm của Agent
- Bạn là một agent giám sát. Nhiệm vụ của bạn là quan sát và báo cáo, không phải thực hiện thay đổi.
- Khi phát hiện sự cố, hãy ghi chúng vào ./alerts/[timestamp].json
- Không bao giờ sửa đổi các file trong ./src/ hoặc ./config/
- Nếu phát hiện sự cố nghiêm trọng, hãy thêm tóm tắt vào ./alerts/critical.log

## Ý nghĩa của "Nghiêm trọng"
- Tỷ lệ lỗi trên 5% trong giờ qua
- Thời gian phản hồi trung bình trên 2000ms
- Lỗi kết nối cơ sở dữ liệu
- Bất kỳ lỗi 5xx nào từ endpoint /api/payments

## Quy trình xử lý
Đối với cảnh báo nghiêm trọng, hãy chạy /scripts/notify-oncall.sh với chi tiết cảnh báo.
Đối với cảnh báo thông thường, chỉ ghi thêm vào /alerts/warnings.log.

Xây dựng Agent theo lịch trình đầu tiên

Dưới đây là hướng dẫn chi tiết về cách xây dựng một agent giám sát nhật ký chạy mỗi giờ.

Bước 1: Xác định phạm vi của Agent

Trước khi viết bất kỳ cấu hình nào, hãy cụ thể về:

1. Dữ liệu nào mà agent cần truy cập
2. Những quyết định nào mà agent đưa ra
3. Những hành động nào mà agent thực hiện
4. Cách agent báo cáo kết quả

Trong ví dụ này, agent đọc nhật ký ứng dụng, xác định lỗi trong giờ qua và ghi vào file cảnh báo nếu có bất kỳ điều gì cần chú ý.

Bước 2: Viết Shell Wrapper Script

Tạo một script gọi Claude Code:

#!/bin/bash
# /opt/agents/log-monitor.sh

# Load environment variables
source /etc/environment

# Set working directory — always use absolute paths in scheduled scripts
cd /var/www/myapp || { echo "Cannot navigate to project directory"; exit 1; }

# Generate a timestamp for this run
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
LOG_FILE="/var/log/agent-runs/monitor-${TIMESTAMP}.log"

echo "Agent run started: ${TIMESTAMP}" >> "$LOG_FILE"

# Run the agent
claude -p "
You are a log monitoring agent running an automated check.

Current time: ${TIMESTAMP}

Your task:
1. Read ./logs/app.log and ./logs/error.log
2. Find any lines with level ERROR or FATAL from the last 60 minutes
3. Categorize each issue by severity: critical, warning, or informational
4. If there are critical or warning issues, write a JSON file to ./alerts/${TIMESTAMP}.json with:
   - timestamp
   - severity
   - affected_component
   - error_message
   - suggested_action
5. If everything looks healthy, write 'HEALTHY: ${TIMESTAMP}' to ./status/latest.txt

If you cannot read a log file, note that in your output and continue with what you can access.
" \
  --allowedTools "Bash,Read,Write" \
  --max-turns 15 \
  --output-format json \
  >> "$LOG_FILE" 2>&1

EXIT_CODE=$?

echo "Agent run completed with exit code: ${EXIT_CODE}" >> "$LOG_FILE"

# Alert if the agent itself failed
if [ $EXIT_CODE -ne 0 ]; then
  /scripts/notify-team.sh "Agent log-monitor failed (exit code $EXIT_CODE). Check $LOG_FILE"
fi

#!/bin/bash
# /opt/agents/log-monitor.sh

# Load các biến môi trường
source /etc/environment

# Thiết lập thư mục làm việc — luôn sử dụng đường dẫn tuyệt đối trong các script theo lịch trình
cd /var/www/myapp || { echo "Cannot navigate to project directory"; exit 1; } }

# Tạo timestamp cho lần chạy này
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
LOG_FILE="/var/log/agent-runs/monitor-${TIMESTAMP}.log"

echo "Agent run started: ${TIMESTAMP}" >> "$LOG_FILE"

# Chạy tác vụ
claude -p "
Bạn là một agent giám sát nhật ký đang chạy một kiểm tra tự động.

Thời gian hiện tại: ${TIMESTAMP}

Nhiệm vụ của bạn:
1. Đọc ./logs/app.log và ./logs/error.log
2. Tìm bất kỳ dòng nào có mức độ LỖI hoặc NGHIÊM TRỌNG trong 60 phút qua
3. Phân loại từng sự cố theo mức độ nghiêm trọng: nghiêm trọng, cảnh báo hoặc thông tin
4. Nếu có sự cố nghiêm trọng hoặc cảnh báo, hãy ghi một file JSON vào ./alerts/${TIMESTAMP}.json với:
  - timestamp
  - mức độ nghiêm trọng
  - thành phần bị ảnh hưởng
  - thông báo lỗi
  - hành động được đề xuất
5. Nếu mọi thứ đều ổn, hãy ghi 'HEALTHY: ${TIMESTAMP}' vào ./status/latest.txt

Nếu bạn không thể đọc file nhật ký, hãy ghi chú điều đó trong đầu ra của bạn và tiếp tục với những gì bạn có thể truy cập.
" \
  --allowedTools "Bash,Read,Write" \
  --max-turns 15 \
  --output-format json \
  >> "$LOG_FILE" 2>&1

EXIT_CODE=$?

echo "Agent run completed with exit code: ${EXIT_CODE}" >> "$LOG_FILE"

# Cảnh báo nếu chính tác vụ bị lỗi
if [ $EXIT_CODE -ne 0 ]; then
  /scripts/notify-team.sh "Agent log-monitor failed (exit code $EXIT_CODE). Check $LOG_FILE"
fi

Một vài điều cần lưu ý ở đây:

• Luôn sử dụng đường dẫn tuyệt đối. Thư mục làm việc không thể dự đoán được trong các ngữ cảnh đã lên lịch.
• Ghi lại exit code. Claude Code trả về giá trị khác 0 khi thất bại.
• Bao gồm timestamp hiện tại trong prompt. Agent không nhận biết được đồng hồ thời gian thực trừ khi bạn cung cấp nó.
• Ghi nhật ký mọi thứ. Bạn sẽ cần những nhật ký đó khi gỡ lỗi sự cố lúc 3 giờ sáng.

Bước 3: Kiểm tra trước khi lên lịch

Chạy thủ công trước:

chmod +x /opt/agents/log-monitor.sh
/opt/agents/log-monitor.sh

Kiểm tra nhật ký đầu ra. Chú ý đến:

• Lỗi quyền truy cập công cụ — Điều chỉnh --allowedTools nếu agent không thể truy cập những gì nó cần
• Sự cố đường dẫn — Nếu agent báo cáo không tìm thấy tệp, hãy kiểm tra thiết lập thư mục làm việc của bạn
• Sự mơ hồ của prompt — Nếu agent thực hiện điều gì đó không mong đợi, hướng dẫn của bạn cần phải cụ thể hơn

Lặp lại quá trình chỉnh sửa file CLAUDE.md và prompt cho đến khi hành vi chính xác như bạn muốn.

Bước 4: Thêm cron job

Sau khi script chạy đúng cách, hãy lên lịch cho nó:

crontab -e

Thêm lịch trình của bạn:

# Run log monitor every hour
0 * * * * /opt/agents/log-monitor.sh

# Run daily summary every morning at 7am
0 7 * * * /opt/agents/daily-summary.sh

# Run security scan every Sunday at 2am
0 2 * * 0 /opt/agents/security-scan.sh

# Chạy trình giám sát nhật ký mỗi giờ
0 * * * * /opt/agents/log-monitor.sh

# Chạy báo cáo tóm tắt hàng ngày mỗi sáng lúc 7 giờ
0 7 * * * /opt/agents/daily-summary.sh

# Chạy quét bảo mật mỗi Chủ nhật lúc 2 giờ sáng
0 2 * * 0 /opt/agents/security-scan.sh

Hướng dẫn nhanh về cú pháp cron:

┌───────────── minute (0–59)
│ ┌───────────── hour (0–23)
│ │ ┌───────────── day of month (1–31)
│ │ │ ┌───────────── month (1–12)
│ │ │ │ ┌───────────── day of week (0–6, Sunday=0)
│ │ │ │ │
* * * * * command

Hãy sử dụng crontab.guru để kiểm tra tính hợp lệ của các biểu thức lập lịch trước khi triển khai chúng.

Những điểm chính cần ghi nhớ

Việc xây dựng các AI agent theo lịch trình đáng tin cậy với Claude Code dựa trên một số nguyên tắc cốt lõi:

• Sử dụng -p để tự động hóa — Chế độ không tương tác là nền tảng. Nếu không có nó, việc lập lịch trình là không thể.
• CLAUDE.md chứa các lệnh thường trực của bạn — Ngữ cảnh, ràng buộc và chính sách leo thang được lưu trữ ở đó. Mỗi lần chạy theo lịch trình sẽ tự động kế thừa chúng.
• Viết prompt với phân nhánh rõ ràng — Cho agent biết phải làm gì trong mỗi kịch bản, bao gồm cả khi nào cần leo thang và khi nào không cần làm gì.
• Thiết kế để chạy lại — Các agent sẽ chạy lại sau khi gặp lỗi. Thiết kế tác vụ bất biến ngăn chặn việc chạy lại gây ra các vấn đề mới.
• Theo dõi mọi thứ — Nhật ký có cấu trúc, kiểm tra exit code và giám sát heartbeat là cách bạn biết các agent của mình đang hoạt động.
• Xây dựng các lớp bảo vệ — Quyền hạn cấp hệ điều hành cộng với hướng dẫn cấp agent đáng tin cậy hơn so với chỉ sử dụng một trong hai.

Sự kết hợp giữa khả năng suy luận của Claude Code và cơ sở hạ tầng lập lịch tiêu chuẩn cung cấp cho bạn các agent tự động có thể xử lý công việc vận hành thực tế — mà không cần nền tảng điều phối chuyên dụng hoặc đầu tư cơ sở hạ tầng đáng kể.