Triển khai và bảo mật tác nhân AI với AI Agent Gateway

AI Agent Gateway là gì?

AI Agent Gateway là một dịch vụ mã nguồn mở nằm giữa các tác nhân AI và những hệ thống mà chúng gọi đến. Dịch vụ cung cấp một điểm truy cập duy nhất có xác thực và khả năng giám sát cho các máy chủ công cụ MCP và các nhà cung cấp LLM được hỗ trợ, bao gồm Anthropic Claude, AWS Bedrock, OpenAI và Gemini.

Thay vì sao chép thông tin xác thực công cụ và cài đặt nhà cung cấp vào từng tác nhân, bạn có thể quản lý tập trung việc xác thực, bí mật, chính sách truy cập và nhật ký yêu cầu. Gateway được phân phối dưới dạng một tệp nhị phân duy nhất và tích hợp sẵn bảng điều khiển quản trị.

Dịch vụ cung cấp ba trình lắng nghe:

• Mặt phẳng MCP trên cổng 8080: Nhận yêu cầu MCP từ các tác nhân và chuyển tiếp những thao tác được cho phép đến các máy chủ công cụ đã đăng ký.
• Mặt phẳng điều khiển trên cổng 8081: Cung cấp REST API và bảng điều khiển quản trị.
• Mặt phẳng LLM trên cổng 8082: Proxy các yêu cầu LLM được hỗ trợ và ghi lại thông tin sử dụng.

PostgreSQL là bắt buộc. Kho phiên tương thích với Redis là tùy chọn và cho phép mặt phẳng MCP chạy với nhiều hơn một bản sao; các bản triển khai đi kèm sử dụng Valkey. ClickHouse là tùy chọn và cung cấp các tính năng phân tích bổ sung.

Tính năng chính

• Xác thực mọi yêu cầu: Khóa API do gateway cấp được giới hạn theo tenant và vai trò.
• Bảo vệ thông tin xác thực của connector: Thông tin xác thực được lưu trong kho bí mật đã mã hóa và được chèn vào các yêu cầu MCP gửi đi mà không để lộ cho bên gọi.
• Chính sách công cụ riêng cho từng tác nhân: Các hồ sơ có thể giới hạn những công cụ mà một tác nhân được phép sử dụng. Các hạn chế được thực thi trong tools/call, không chỉ khi liệt kê công cụ.
• Prompt và tài nguyên: Gateway chuyển tiếp prompt và tài nguyên từ backend qua một không gian tên dùng chung, đồng thời áp dụng các chính sách hồ sơ tương tự.
• Kỹ năng và lệnh: Hồ sơ có thể bao gồm văn bản tham chiếu có thể tái sử dụng và các mẫu prompt được cung cấp thông qua cơ chế MCP gốc.
• Proxy LLM đa nhà cung cấp: Mặt phẳng LLM hỗ trợ Anthropic, Bedrock, OpenAI và Gemini, đồng thời ghi nhận số token sử dụng và chi phí ước tính.
• Khả năng giám sát tập trung: Bảng điều khiển cung cấp nhật ký truy cập, nhật ký LLM, dòng thời gian phiên và bảng điều khiển phân tích khi bật bộ lưu trữ cần thiết.
• Bảo vệ yêu cầu gửi đi: Các đích nội bộ, loopback, liên kết cục bộ và những đích riêng tư khác bị chặn theo mặc định nhằm giảm rủi ro giả mạo yêu cầu phía máy chủ.

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

Cách thiết lập nhanh nhất là sử dụng Docker Compose. Trước khi bắt đầu, hãy cài đặt hoặc kiểm tra các thành phần sau:

• Docker có plugin Compose, chẳng hạn như Docker Desktop, Colima hoặc Docker Engine.
• curl để kiểm tra tình trạng hoạt động và jq để xử lý phản hồi API.
• Các cổng cục bộ 8080, 8081 và 8082 còn trống.
• Cổng 8090 nếu bạn bật profile phân tích và dịch vụ Adminer đi kèm.
• Ít nhất 4 GB dung lượng Docker trống, hoặc 8 GB khi thêm tính năng phân tích ClickHouse.

macOS và Linux được hỗ trợ. Windows có thể được sử dụng thông qua WSL2, mặc dù môi trường này hiện chưa được kiểm thử.

Để build bên ngoài Docker, repository yêu cầu Go 1.27, Node.js 26 cho bảng điều khiển và make. Một số ví dụ thực hành còn yêu cầu npx, Python, kind, kubectl hoặc khóa API của nhà cung cấp.

Cài đặt và khởi động Gateway

1. Clone repository

git clone https://github.com/Tuskira/ai-agent-gateway.git
cd ai-agent-gateway

2. Khởi chạy stack Compose tiêu chuẩn

docker compose -f deploy/docker-compose.yml up --build -d

Lần khởi động đầu tiên có thể mất một chút thời gian vì Docker phải build hoặc tải xuống các thành phần cần thiết và khởi tạo cơ sở dữ liệu.

3. Chờ mặt phẳng điều khiển

until curl -sf localhost:8081/api/v1/health >/dev/null; do sleep 1; done

Vòng lặp này chờ cho đến khi endpoint kiểm tra tình trạng hoạt động của mặt phẳng điều khiển trả về thành công.

4. Kiểm tra cả ba mặt phẳng

curl localhost:8080/health
curl localhost:8081/api/v1/health
curl localhost:8082/health

Phản hồi thành công xác nhận các trình lắng nghe MCP, điều khiển và LLM đều khả dụng.

Khởi tạo quyền truy cập quản trị

Một bản triển khai mới không có người dùng bảng điều khiển và cũng không có khóa API. Hãy bắt đầu bằng cách tạo tenant mặc định và khóa API quản trị:

docker compose -f deploy/docker-compose.yml exec gateway /gateway bootstrap-key

Lệnh chỉ in khóa API một lần duy nhất. Hãy lưu khóa một cách an toàn vì quy trình bắt đầu sử dụng cần khóa này để đăng ký connector và thực hiện các thao tác API quản trị.

Tiếp theo, tạo người dùng bảng điều khiển đầu tiên:

docker compose -f deploy/docker-compose.yml exec gateway /gateway create-user -tenant default -username admin -role admin

Lệnh này in ra mật khẩu tạm thời chỉ dùng một lần. Mở http://localhost:8081, đăng nhập bằng admin và đổi mật khẩu tạm thời khi được yêu cầu.

Các chương trình thường nên xác thực bằng khóa API. Bảng điều khiển cũng có thể chấp nhận khóa API như một phương án dự phòng khẩn cấp.

Cách sử dụng cơ bản: Thêm và gọi máy chủ MCP

Trong thuật ngữ của gateway, máy chủ công cụ MCP là một connector trong API và là một MCP trong bảng điều khiển. Sau khi đăng nhập, mở MCPs → Catalog để xem các máy chủ MCP dựng sẵn có thể thêm vào.

Quy trình sử dụng lần đầu thông thường là:

1. Tạo và lưu khóa API quản trị viên.
2. Đăng ký máy chủ MCP dưới dạng một connector.
3. Cấu hình mọi thông tin xác thực mà connector cần.
4. Tạo hoặc chọn một hồ sơ agent.
5. Cung cấp các công cụ của connector cho hồ sơ đó.
6. Gọi một công cụ được cấp phép thông qua MCP listener của gateway trên cổng 8080.
7. Kiểm tra lệnh gọi trong console quản trị.

Kho lưu trữ chứa hướng dẫn thực thi hoàn chỉnh tại examples/01-quickstart. Hướng dẫn này khởi động stack, xác minh cả ba plane, khởi tạo khóa quản trị viên, đăng ký một máy chủ MCP mẫu và gọi một trong các công cụ của máy chủ. Hãy làm theo hướng dẫn bắt đầu để xem chính xác các yêu cầu đăng ký connector và gọi công cụ.

Để chạy tất cả ví dụ không yêu cầu thông tin xác thực bên ngoài, hãy sử dụng:

make examples-smoke

Hồ sơ Agent Thực thi Quyền Truy cập Như thế nào

Hồ sơ xác định các công cụ, lời nhắc, tài nguyên, kỹ năng và lệnh có sẵn cho một agent. Các hạn chế công cụ được kiểm tra khi agent gọi tools/call, vì vậy việc ẩn công cụ khỏi tools/list không phải là lớp thực thi duy nhất.

Để thực thi chính sách chặt chẽ hơn, hãy liên kết khóa API với một hồ sơ. Nếu không có liên kết, bên gọi có thể chỉ định hồ sơ mong muốn thông qua header X-Agent-Profile-Name. Liên kết khóa với hồ sơ ngăn bên gọi tự do chọn một hồ sơ khác.

Khi nhiều máy chủ MCP cung cấp lời nhắc hoặc tài nguyên, gateway duy trì chúng trong một namespace chung. Lời nhắc được định danh kèm tên connector, còn tài nguyên sử dụng URI do gateway quản lý. Các quy tắc hồ sơ tương tự quyết định những mục nào agent có thể truy cập.

Sử dụng LLM Proxy

LLM plane cung cấp một tuyến tập trung đến các nhà cung cấp mô hình được hỗ trợ: Anthropic, AWS Bedrock, OpenAI và Gemini. Điều này cho phép các ứng dụng agent gửi lưu lượng mô hình qua cùng một bề mặt được kiểm soát dùng cho các công cụ.

Với mỗi lệnh gọi được proxy, gateway có thể ghi nhận mức sử dụng token và ước tính chi phí. Thiết lập nhà cung cấp, cấu hình sử dụng khóa riêng, các chế độ thông tin xác thực Bedrock, tuyến, cài đặt ghi nhận và cách tính chi phí được trình bày trong hướng dẫn LLM plane.

Hãy sử dụng health endpoint để xác minh listener trước khi cấu hình client:

curl localhost:8082/health

Bật Analytics

Triển khai tiêu chuẩn hỗ trợ nhật ký LLM mà không cần ClickHouse. Để thêm dashboard Overview, Access Logs, Session Timeline và analytics dựa trên ClickHouse, hãy khởi động Compose với profile analytics:

GATEWAY_SINKS_CLICKHOUSE_ENABLED=true docker compose -f deploy/docker-compose.yml --profile analytics up --build -d

Cấu hình này yêu cầu nhiều tài nguyên cục bộ hơn và có thể sử dụng cổng 8090.

Bảo vệ Nội dung Body Nhạy cảm của Request

Stack minh họa lưu nội dung body của request và response LLM trong PostgreSQL, với giới hạn 1 MiB cho mỗi nội dung. Với profile analytics, stack cũng lưu nội dung body của request và response LLM và MCP trong ClickHouse để hiển thị trong console. Các nội dung body này không được in vào nhật ký container.

Nếu lời nhắc, phản hồi mô hình hoặc payload công cụ có thể chứa thông tin nhạy cảm, hãy tắt hoàn toàn việc lưu nội dung body:

GATEWAY_LLM_PROXY_CAPTURE_STORE_BODIES=false GATEWAY_CAPTURE_STORE_BODIES=false docker compose -f deploy/docker-compose.yml up --build -d

Hãy xem lại tài liệu về khả năng quan sát trước khi sử dụng các tính năng ghi nhận với dữ liệu production.

Kết nối An toàn với Máy chủ MCP Cục bộ hoặc Riêng tư

The gateway chặn các đích loopback, private, link-local và các đích nội bộ khác theo mặc định. Gateway cũng chặn vĩnh viễn địa chỉ metadata đám mây 169.254.169.254. Chính sách này ngăn connector, mục catalog hoặc đích mô hình âm thầm truy cập các dịch vụ nhạy cảm trên máy chủ hoặc mạng.

Nếu một hostname chỉ phân giải thành các địa chỉ bị chặn khi được tạo, gateway sẽ từ chối hostname đó với 400 egress_blocked. Hostname chưa phân giải được vẫn có thể được chấp nhận, nhưng sẽ được kiểm tra lại khi gateway cố gắng kết nối.

Chạy trực tiếp binary

Khi chạy bằng make run, hãy cho phép loopback một cách rõ ràng nếu máy chủ MCP đang chạy trên cùng máy:

GATEWAY_EGRESS_ALLOWED_CIDRS=127.0.0.0/8,::1/128 make run

Sử dụng Stack Compose Được Cung cấp

Cấu hình Compose đi kèm đã cho phép host.docker.internal và các CIDR loopback. Vì vậy, máy chủ chạy trên laptop của bạn có thể được truy cập thông qua host.docker.internal. Hãy xóa các quyền cho phép này trong môi trường dùng chung, trừ khi chúng thực sự cần thiết.

Sử dụng Kubernetes hoặc Mạng Riêng

Đối với một dịch vụ Kubernetes trong cluster, chỉ cho phép tên DNS đang được gọi, ví dụ:

GATEWAY_EGRESS_ALLOWED_HOSTS=my-mcp-server.my-ns.svc

Bạn cũng có thể cho phép CIDR của pod hoặc service tương ứng. Đối với các máy chủ chỉ dùng qua VPN hoặc mạng riêng, hãy thêm hostname cụ thể hoặc CIDR hẹp thay vì bật toàn bộ dải địa chỉ private.

Giữ allowlist outbound ở phạm vi hẹp nhất có thể. Không tắt cơ chế bảo vệ chỉ để việc kiểm thử ban đầu dễ dàng hơn.

Mẹo Vận hành Nâng cao

• Tách quyền truy cập của con người và chương trình: Sử dụng tài khoản console cho quản trị viên và khóa API do gateway cấp cho tác nhân và các quy trình tự động.
• Liên kết khóa với profile: Khóa được liên kết với profile mang lại sự đảm bảo chặt chẽ hơn so với việc cho phép bên gọi tự chọn profile bằng header yêu cầu.
• Lưu thông tin xác thực trong gateway: Cấu hình thông tin xác thực của connector tập trung để tác nhân không nhận được các bí mật nền tảng.
• Luân phiên thông tin xác thực của connector: Sử dụng các tính năng quản lý connector và thông tin xác thực thay vì cập nhật độc lập từng tác nhân.
• Kiểm soát việc ghi lại dữ liệu: Quyết định có lưu giữ phần thân của yêu cầu và phản hồi hay không trước khi xử lý các prompt mật hoặc kết quả công cụ.
• Lập kế hoạch cho nhiều bản sao: Cấu hình session store sử dụng giao thức Redis tùy chọn khi mở rộng lớp MCP vượt quá một bản sao.
• Sử dụng quy tắc egress giới hạn: Cho phép từng máy chủ hoặc CIDR cụ thể thay vì các dải mạng riêng tư rộng.
• Tham khảo các ví dụ thực tế: Từng ví dụ bao quát các kịch bản bổ sung và liệt kê mọi công cụ hoặc khóa nhà cung cấp cần thiết trong tệp README riêng.
• Dự kiến sẽ có thay đổi: Dự án đang ở giai đoạn alpha trước phiên bản 1.0, vì vậy API và cấu hình có thể thay đổi giữa các phiên bản minor.

Xây dựng bên ngoài Docker

Để phát triển cục bộ, hãy cài đặt Go 1.27, Node.js 26 và make. Kho mã cung cấp các quy trình make build và make run. Các công cụ phát triển và phát hành tùy chọn gồm golangci-lint, govulncheck và goreleaser.

Để biết các quy ước phát triển, lệnh kiểm thử, hướng dẫn pull request và các điểm mở rộng cho store, sink và provider, hãy xem hướng dẫn đóng góp.

Kết luận

AI Agent Gateway tập trung hóa quyền truy cập vào các công cụ MCP và nhiều nhà cung cấp LLM phía sau các endpoint được xác thực. Các tính năng thực thi profile, chèn thông tin xác thực, kiểm soát mạng hướng ra ngoài và khả năng quan sát giúp giữ chính sách cùng bí mật bên ngoài cấu hình của từng tác nhân.

Hãy bắt đầu với hướng dẫn nhanh Docker Compose, lưu khóa quản trị viên được tạo, tạo người dùng console và hoàn tất quy trình connector đầu tiên. Sau đó, thêm các khóa API liên kết với profile, cấu hình quyền truy cập nhà cung cấp, chọn chính sách ghi lại phần thân phù hợp và chỉ bật tính năng phân tích ClickHouse khi cần khả năng quan sát bổ sung.