Pigeon: Tấm vé ký số giới hạn quyền hạn cho các sub-agent AI

Khi các tác nhân AI (agent) ngày càng phổ biến, việc chúng tự tạo ra các agent con để xử lý công việc trở nên thường xuyên hơn. Nhưng nếu bạn trao toàn bộ API key cho một sub-agent, nó có thể tự do deploy lên production, đọc database thanh toán hay merge code vào nhánh chính — một thảm họa bảo mật tiềm tàng. Pigeon ra đời để giải quyết vấn đề này bằng cách cấp cho agent con một "Pass" ký số chỉ định rõ những gì nó được phép làm, thay vì sao chép toàn bộ quyền từ agent cha.

Ý tưởng cốt lõi trong 20 dòng code

Pigeon được thiết kế tối giản. Bạn chỉ cần sử dụng hai hàm chính:

• grant() để tạo ra một quyền hạn (authority) cho một agent cụ thể.
• verify() để kiểm tra xem một hành động có được phép thực hiện hay không.

from pigeon import grant, verify

authority = grant(
    subject="agent:deployer",
    capabilities=["deploy"],
    resources=["environment:staging"],
)

allowed = verify(authority, action="deploy", resource="environment:staging")
assert allowed.allowed

denied = verify(authority, action="deploy", resource="environment:production")
assert not denied.allowed
assert denied.reason_code == "RESOURCE_NOT_ALLOWED"

Điểm đáng chú ý là verify() không bao giờ trả về kiểu boolean đơn thuần. Khi từ chối, nó cung cấp đầy đủ mã lý do, thông báo và chi tiết so sánh giữa yêu cầu và quyền cho phép. Nhờ đó bạn hiểu được chính xác vì sao một thao tác bị chặn.

Vị trí của Pigeon trong hệ thống agent

Pigeon không yêu cầu một máy chủ riêng. Bạn chỉ cần thay đổi hai điểm trong luồng hoạt động hiện tại:

1. Khi spawn sub-agent: Thay vì copy API key, hãy dùng hàm delegate() để tạo ra một Pass thu hẹp hơn cho agent con.
2. Tại điểm thực thi hành động: Nơi diễn ra các side effect như deploy, query, hay gọi MCP tool, hãy gọi verify() và chặn hành động nếu không được cấp phép.

Điểm mấu chốt: Giữ bí mật thật sự trên máy chạy chính (runner), agent con chỉ mang theo Pass.

from pigeon import delegate, grant, verify, DelegationError

parent = grant(
    subject="agent:orchestrator",
    capabilities=["deploy", "open_pr"],
    resources=["environment:staging", "repo:acme/api"],
    constraints={"max_deploys_per_hour": 3},
)

worker = delegate(
    parent,
    subject="agent:pr-bot",
    capabilities=["open_pr"],
    resources=["repo:acme/api"],
    constraints={"max_deploys_per_hour": 3},  # không thể bỏ ràng buộc của cha
)

Cơ chế chống leo thang đặc quyền

Điểm an toàn quan trọng nhất của Pigeon là một agent con không thể:

• Thêm các capability mới.
• Mở rộng phạm vi resource.
• Nâng giới hạn (bound).
• Loại bỏ ràng buộc từ agent cha.

Nếu Pigeon không thể chứng minh rằng quyền của agent con hẹp hơn agent cha, nó sẽ từ chối ngay lập tức. Trong trường hợp này bạn dùng vòng lặp:

try:
    delegate(worker, "agent:rogue", ["open_pr", "deploy"], ["repo:acme/api"])
except DelegationError as exc:
    assert exc.reason_code == "PRIVILEGE_ESCALATION"

Điều này đặc biệt quan trọng với các doanh nghiệp Việt Nam đang xây dựng hệ thống tự động hóa, bởi một lỗ hổng nhỏ trong chuỗi agent có thể dẫn đến hậu quả nghiêm trọng.

Tích hợp MCP middleware

Pigeon cũng hỗ trợ MCP (Model Context Protocol) — một giao thức ngày càng phổ biến để kết nối AI với các công cụ bên ngoài. Thư viện cung cấp middleware cho phép client tạo ra một Pass thu hẹp cho từng lệnh gọi tool, và server xác minh trước khi thực thi.

from pigeon import grant
from pigeon.integrations.mcp import execute_tool, pass_for_tool

parent = grant(
    subject="agent:github",
    capabilities=["create_issue", "merge_pr"],
    resources=["mcp:github"],
)

tool_pass = pass_for_tool(parent, "create_issue", "mcp:github")

ok = execute_tool(tool_pass, "create_issue", "mcp:github",
                  {"title": "bump deps", "body": "automated"}, create_issue)
assert ok["allowed"]

no = execute_tool(tool_pass, "merge_pr", "mcp:github",
                  {"title": "nope", "body": "nope"}, create_issue)
assert no["reason_code"] == "CAPABILITY_NOT_GRANTED"

Những gì Pigeon KHÔNG phải là

Pigeon được giới thiệu như một "nguyên thủy nhỏ" (small primitive), không phải là:

• Một nền tảng hoàn chỉnh.
• Một policy engine phức tạp.
• Một identity provider.
• Một dịch vụ quản lý khóa.

Ngoài ra, nó không chống lại prompt injection — một vấn đề khác mà bạn cần giải quyết riêng. Pigeon chỉ giúp giới hạn phạm vi thiệt hại dọc theo các chiều bạn đưa vào Pass.

Góc nhìn cho nhà phát triển Việt Nam

Trong bối cảnh các mô hình AI tự hành (autonomous agents) đang bùng nổ, việc kiểm soát quyền truy cập trở thành bài toán cấp thiết tại mọi công ty công nghệ. Pigeon cung cấp một cách tiếp cận nhẹ nhàng, dễ tích hợp, và có thể áp dụng ngay với các dự án Python 3.12+. Với những đội nhóm đang xây dựng hệ thống DevOps, tự động hóa quy trình, hay tích hợp AI vào quy trình phát triển phần mềm, đây là một công cụ đáng để thử nghiệm.

Thư viện đang phát triển với mã nguồn mở trên GitHub, kèm spec và tài liệu bảo mật chi tiết trong repository chính thức.