Chuyển đến nội dung chính
Hướng dẫn AI

Kết nối các ứng dụng AI với Tetrees Agent bằng MCP và Public API

Tìm hiểu cách cấu hình MCP của Tetrees Agent được lưu trữ, kiểm tra hợp đồng công khai, sử dụng CLI của API, chạy các AI Pack đã được báo giá, liên kết tiện ích mở rộng cục bộ và thực hiện quy trình dành cho người bán được hỗ trợ mà không để lộ thông tin xác thực hay các khả năng riêng tư.

Thời gian đọc khoảng 21 phút
Kết nối ứng dụng AI với Tetrees Agent bằng MCP và Public API

Tetrees Agent EX là gì?

Tetrees Agent EX là bộ công cụ tích hợp công khai để làm việc với Tetrees AI Packs thông qua máy chủ MCP và API Tetrees Agent được lưu trữ. Bộ công cụ cung cấp các client, ví dụ cấu hình và mẫu mở rộng an toàn cho người mua, nhà xây dựng và người bán.

Tích hợp Tetrees Agent AI Pack

Bộ công cụ công bố hợp đồng dành cho nhà phát triển thay vì nội bộ của dịch vụ được lưu trữ. Bộ công cụ không bao gồm chi tiết triển khai Tetrees Agent, dữ liệu trí tuệ riêng của Pack, quy tắc chấm điểm Agent AVCP, prompt dịch vụ, hệ thống kiểm duyệt, hạ tầng lưu trữ hoặc thông tin xác thực production.

Các hoạt động do Tetrees lưu trữ không yêu cầu GPU cục bộ. Các lượt chạy do mô hình tài trợ được báo giá bằng Tetrees Points trước khi thực thi. Sau khi mua một Pack, người dùng cũng có thể cung cấp khóa của nhà cung cấp được hỗ trợ cho tiến trình MCP cục bộ.

Bạn có thể xây dựng gì?

Quy trình cho người mua và người vận hành

Người mua và người vận hành có thể sử dụng hợp đồng công khai để:

  • Tìm kiếm danh mục AI Pack.
  • Xem báo cáo Agent AVCP công khai và hồ sơ runtime của một Pack.
  • Báo giá một lượt chạy trước khi sử dụng Tetrees Points.
  • Dùng thử một Pack thông qua bản xem trước không trạng thái được tài trợ bằng Points.
  • Mua một Pack miễn phí hoặc trả phí trên Tetrees EX.
  • Tải xuống bản phát hành .taip bất biến mà tài khoản sở hữu.

Quy trình cho nhà xây dựng

Nhà xây dựng có thể kết nối một Pack đã được thử nghiệm với các khả năng do người dùng kiểm soát, đồng thời giữ các liên kết và thông tin xác thực trên máy của người dùng. Các mẫu được hỗ trợ gồm API HTTPS cố định, máy chủ MCP lồng nhau và skill cục bộ không dùng shell.

Quy trình cho người bán

Người bán có thể tạo tin đăng, tải lên các phiên bản và hình ảnh Pack bất biến, kiểm tra trạng thái sẵn sàng, chạy Agent AVCP, xem phản hồi sửa lỗi riêng tư và phát hành bản phát hành vượt qua đánh giá.

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

Trước khi cấu hình tích hợp MCP được lưu trữ, hãy chuẩn bị:

  • Node.js 20 trở lên.
  • Một token API có thể thu hồi từ trang Tài khoản Tetrees.
  • Một client tương thích với MCP nếu bạn dự định sử dụng máy chủ MCP được lưu trữ.
  • Một bản checkout cục bộ của repository nếu bạn muốn chạy inspector, CLI, các ví dụ hoặc lệnh xác minh.

Không đưa thông tin xác thực vào Pack, prompt, tệp mã nguồn hoặc cấu hình MCP dùng chung. Các khóa nhà cung cấp tùy chọn chỉ nên tồn tại trong môi trường của tiến trình MCP cục bộ.

Cấu hình máy chủ MCP được lưu trữ

Thêm định nghĩa máy chủ sau vào cấu hình của client MCP. Thay phần giữ chỗ bằng token tài khoản Tetrees có thể thu hồi của bạn.

{
  "mcpServers": {
    "tetrees-ai": {
      "command": "npx",
      "args": ["-y", "https://ex.tetrees.ai/pkg/tetrees-mcp.tgz?v=2.2.0"],
      "env": {
        "TETREES_API_URL": "https://ex.tetrees.ai/api",
        "TETREES_TOKEN": "<revocable-account-token>"
      }
    }
  }
}

Khởi động lại client MCP sau khi lưu cấu hình. Hậu tố v=2.2.0 ngăn npx sử dụng lại tarball cũ được lưu trong bộ nhớ đệm dưới cùng URL. Chỉ thay đổi giá trị này khi Tetrees phát hành hợp đồng MCP mới hơn.

Thử một yêu cầu MCP an toàn

Yêu cầu client MCP tìm kiếm và báo giá một Pack mà không bắt đầu lượt chạy trả phí:

Search Tetrees AI Packs for repository issue triage. Show the public Agent AVCP
report and runtime profile for the best match, then quote an 8k/2k Point-funded
run. Do not run it until I approve the quoted maximum.

Yêu cầu này tuân theo mẫu an toàn dự kiến: tìm một Pack, xem đánh giá công khai và yêu cầu runtime của Pack, yêu cầu báo giá rồi chờ phê duyệt rõ ràng trước khi sử dụng Points.

Kiểm tra hợp đồng MCP công khai

Từ thư mục repository, cài đặt các dependency, xuất token và chạy MCP inspector:

npm install
export TETREES_TOKEN="txk_..."
npm run mcp:inspect

Inspector khởi chạy gói MCP chính thức được lưu trữ và liệt kê các tool cùng resource công khai. Inspector cũng kiểm tra các bề mặt dự kiến dành cho người mua, nhà xây dựng và người bán. Quá trình kiểm tra kết thúc mà không sử dụng Points hoặc thay đổi trạng thái tài khoản.

Sử dụng CLI API công khai

Dự án cố ý không tự động tải các tệp bí mật. Hãy sao chép các giá trị liên quan từ .env.example vào môi trường shell thay vì chờ CLI đọc chúng.

export TETREES_TOKEN="txk_..."

Chạy các lệnh chỉ đọc

Bắt đầu với các lệnh kiểm tra dịch vụ và tài khoản của bạn mà không khởi tạo tác vụ mô hình:

npm run tetrees -- status
npm run tetrees -- catalog "research"
npm run tetrees -- models
npm run tetrees -- skills
npm run tetrees -- owned
npm run tetrees -- runtime <pack-id>
npm run tetrees -- report <pack-id>

Dùng catalog để tìm Pack, runtime để xem lại hồ sơ runtime và report để kiểm tra báo cáo Agent AVCP công khai. Các lệnh models và skills hiển thị những lựa chọn công khai được hỗ trợ, còn owned liệt kê các Pack liên kết với tài khoản.

Báo giá trước khi chạy

Báo giá không bắt đầu một yêu cầu mô hình. Cung cấp mã định danh Pack và mô hình đã chọn:

npm run tetrees -- quote <pack-id> <model-id>

Xem lại chính xác mô hình, giới hạn token, skill được lưu trữ, mốc kiểm tra tăng trưởng và cam kết Points được báo giá trước khi phê duyệt thực thi.

Xác nhận lượt chạy sử dụng Points

Để bắt đầu một lượt chạy, hãy thêm cờ xác nhận chính xác:

npm run tetrees -- run <pack-id> <model-id> "Your task" --confirm-spend

Bản xem trước được tài trợ bằng Point là phi trạng thái và các Point đã đặt trước nhưng chưa sử dụng sẽ được hoàn lại. CLI sẽ che các trường phản hồi có hình dạng giống bí mật và báo mã lỗi Tetrees, giá trị trạng thái HTTP cùng thông tin Retry-After. CLI không tự động thử lại thao tác thay đổi dữ liệu.

Thực hiện quy trình của người mua

Một quy trình thận trọng dành cho người mua diễn ra theo thứ tự sau:

  1. Tìm kiếm Pack phù hợp với tác vụ.
  2. Kiểm tra báo cáo Agent AVCP công khai và hồ sơ runtime của Pack.
  3. Xác nhận chính xác model, giới hạn token, các skill được lưu trữ và mốc kiểm tra tăng trưởng.
  4. Phê duyệt và chạy bản xem trước phi trạng thái được tài trợ bằng Point.
  5. Nhận Pack miễn phí hoặc mua Pack trả phí thông qua Tetrees EX.
  6. Sử dụng các quyền lợi sở hữu như tải xuống, BYOK, lưu tăng trưởng và các tiện ích mở rộng phía client.

Repository có kèm một ví dụ đã được ghi tài liệu về việc khám phá và báo giá chỉ đọc:

node examples/buyer/discover-and-quote.mjs "incident response"

Thay incident response bằng cụm từ tìm kiếm khác để khám phá Pack cho trường hợp sử dụng khác.

Thêm khả năng cục bộ với tư cách Builder

Một Pack đã xuất bản có thể khai báo các tiện ích mở rộng phía client đã vượt qua Agent AVCP. Việc liên kết và thông tin xác thực thực tế của tiện ích vẫn nằm cục bộ, vì vậy dịch vụ lưu trữ Tetrees không được thừa hưởng các quyền đó.

Chọn mẫu liên kết

  • https_api: Kết nối tới URL cơ sở HTTPS cố định với các phương thức đã khai báo và header lấy từ môi trường.
  • mcp: Khởi động một máy chủ MCP lồng nhau không cần shell và ánh xạ máy chủ đó tới các tên công cụ đã khai báo.
  • local_skill: Khởi động một tiến trình con không cần shell, nhận một yêu cầu JSON và trả về một kết quả JSON.

Sử dụng examples/extensions/client-extensions.example.json làm điểm bắt đầu cấu hình. Repository cũng cung cấp examples/extensions/local-skill/issue-summary.mjs làm ví dụ về local skill và docs/BUILDER_GUIDE.md cho hợp đồng builder đầy đủ.

Một phương thức ghi yêu cầu chính xác cụm từ phê duyệt cho từng lần gọi là APPROVE extensionId.methodId. Không được xem phê duyệt chung trong hội thoại là quyền thực hiện thao tác ghi.

Xuất bản Pack với tư cách Seller

Quy trình dành cho seller được dẫn dắt bởi hợp đồng. Trước tiên, hãy kiểm tra trạng thái sẵn sàng và các báo cáo mà không thay đổi Pack:

node examples/seller/check-readiness.mjs <pack-id>

Khi một bản phát hành mới sẵn sàng, hãy tải lên một phiên bản bất biến cao hơn với xác nhận rõ ràng:

node examples/seller/upload-pack.mjs <pack-id> 1.1.0 ./release.taip --confirm-upload

Sau khi tải lên, hãy sử dụng các công cụ MCP được lưu trữ hoặc tài liệu tham khảo API Tetrees để hoàn tất quy trình xuất bản:

  1. Gửi phiên bản đã tải lên.
  2. Yêu cầu báo giá Agent AVCP.
  3. Xác nhận chính xác số Point trước khi chạy Agent AVCP.
  4. Kiểm tra báo cáo riêng tư và phản hồi sửa lỗi.
  5. Chỉ xuất bản digest đã vượt qua đánh giá.

Tham khảo docs/SELLER_GUIDE.md và examples/seller/pack-listing.example.json khi chuẩn bị thông tin niêm yết.

Mẹo nâng cao về an toàn và độ tin cậy

Tách bí mật khỏi cấu hình dùng chung

Lưu token Tetrees và các khóa nhà cung cấp tùy chọn trong môi trường tiến trình cục bộ. Không bao giờ nhúng thông tin xác thực của nhà cung cấp vào Pack, prompt, tệp mã nguồn hoặc cấu hình có thể được chia sẻ. Sử dụng token có thể thu hồi để rút quyền truy cập khi cần.

Không tự động thử lại các thao tác thay đổi dữ liệu

Đối với các thao tác ghi thất bại, hãy kiểm tra mã lỗi Tetrees, trạng thái HTTP và giá trị Retry-After được báo cáo trước khi quyết định cách xử lý. Việc tự động thử lại có thể lặp lại thao tác tải lên, mua, chạy hoặc các thao tác thay đổi trạng thái khác.

Chủ động ghim hợp đồng MCP được lưu trữ

Giữ nguyên hậu tố truy vấn đã được ghi tài liệu trên URL gói MCP để tránh các mục trong bộ nhớ đệm npx bị cũ. Chỉ cập nhật hậu tố này khi có phiên bản hợp đồng được công bố chính thức.

Kiểm tra ranh giới công khai

Trước khi đóng góp, hãy đọc SECURITY.md và docs/PUBLIC_BOUNDARY.md. Các đóng góp chỉ nên tương tác với hợp đồng công khai đã được ghi tài liệu và xác thực, đồng thời không được giả định quyền truy cập vào nội bộ Agent, dữ liệu Pack riêng tư, bộ dữ liệu chấm điểm, khóa ký, cơ sở dữ liệu, API quản trị hoặc hạ tầng triển khai.

Xác minh repository

Chạy các bước kiểm tra được cung cấp trước khi phân phối thay đổi hoặc chuẩn bị một gói:

npm test
npm run check:public-boundary
npm pack --dry-run

Tài liệu tham khảo công khai hữu ích

Kết luận

Tetrees Agent EX cung cấp một hợp đồng công khai minh bạch để khám phá, đánh giá, chạy, mở rộng và xuất bản Tetrees AI Pack. Hãy bắt đầu bằng việc kiểm tra chỉ đọc, yêu cầu báo giá chính xác trước khi thực hiện công việc được tài trợ bằng model, yêu cầu xác nhận rõ ràng đối với việc chi Point và các thao tác ghi, đồng thời giữ tất cả thông tin xác thực thuộc về người dùng và quyền của tiện ích mở rộng ở cục bộ.