HƯỚNG DẪN TÍCH HỢP

Kết nối dự án.
Database của bạn.

FTA điều phối nhiệm vụ qua HTTPS/JSON. Dự án giữ dữ liệu, quyền truy cập và gate nghiệp vụ của mình. Backend có thể viết bằng bất kỳ ngôn ngữ nào hỗ trợ HTTP.

Đăng ký project →Tải hướng dẫn & prompt

Hai chiều kết nối

Backend dự án → FTA
Bearer token giới hạn tenant/project.

FTA → API dự án
HMAC, Bearer hoặc API key.
API công khai chỉ được khai báo thao tác GET.

SOAP, gRPC, MQTT và hệ thống chỉ có database cần một HTTPS/JSON adapter phía dự án.

1. Đăng ký kết nối

Đăng nhập Gmail quản trị tại console, tạo/chọn tenant và thêm người dùng.
Quản trị server provision API origin và credential reference. Console không tự thêm origin hoặc nhận giá trị secret.
Chọn Kết nối API → Đăng ký project, nhập tên, health path, kiểu xác thực và mảng thao tác API.
Kiểm tra health rồi bật project. Cấu hình mới hoặc vừa sửa luôn tắt; thay đổi bị chặn khi còn run chưa kết thúc.
Tạo token OPERATOR theo project. Backend dự án giữ token trong secret; reviewer dùng APPROVER riêng.

Token hết hạn sau 90 ngày và chỉ hiển thị một lần. Health thành công xác nhận đường kết nối, chưa kiểm chứng nhiệm vụ nghiệp vụ.

2. Khai báo thao tác API

Mỗi project có nhiều capability. Ví dụ dưới đây là cấu hình mẫu cho một API đã có receiver:

{
  "name": "resource.update",
  "description": "Cập nhật tài nguyên theo revision",
  "method": "PATCH",
  "path": "/api/resources/{resourceId}",
  "sideEffect": true,
  "approval": "ALWAYS",
  "idempotent": true,
  "timeoutMs": 10000,
  "request": { "query": ["revision"], "body": ["changes"] },
  "outputField": "data"
}

Input resourceId đi vào path; revision vào query; changes vào JSON body. outputField chọn trường JSON làm output cho expectation và binding của bước sau. Chỉ bật idempotent khi receiver có chống trùng bền vững.

Xác thực outbound	Cấu hình
HMAC	credentialEnv chứa signing secret; receiver kiểm tra raw body và metadata FTA.
BEARER	credentialEnv chứa access token; FTA gửi Authorization: Bearer.
API_KEY	credentialEnv + headerName, ví dụ X-API-Key.
NONE	Không credential, chỉ thao tác GET.

3. Backend gọi runtime

curl --fail https://api.flytrust-agent.io.vn/v1/integrations/contract \
  -H "Authorization: Bearer $FTA_OPERATOR_TOKEN"

import { RuntimeClient } from '@flytrust/agent-runtime/client';
const fta = new RuntimeClient('https://api.flytrust-agent.io.vn',
  process.env.FTA_OPERATOR_TOKEN, { apiPath: '/v1' });
await fta.integrationContract();

Lưu model theo OpenAPI/Workbench, tạo plan READY, submit run với Idempotency-Key ổn định và lưu planId/runId tại dự án. DRY_RUN biên dịch tại chỗ. LIVE cần expectation ngữ nghĩa; mutation đợi approval. Poll run để hiển thị đúng trạng thái lỗi/chờ duyệt/đối soát.

Tải SDK Node 22+ · Ví dụ đầy đủ và prompt cho agent dự án

4. Mỗi dự án giữ database riêng

FTA lưu tenant, cấu hình kết nối, model, plan, run, approval và audit. Dự án giữ dữ liệu nghiệp vụ và tự quản lý migration; không cần mở port database cho FTA.

Outbox dự án

Lưu intent và gửi kế hoạch sang FTA.

FTA runtime

Điều phối và phê duyệt capability.

Receiver dự án

Kiểm tra credential, quyền, intent và revision.

Transaction

Commit receipt chống trùng cùng thay đổi nghiệp vụ.

Cùng key/cùng payload trả receipt đã commit; cùng key/khác payload trả 409. Timeout mutation cần đối chiếu receipt trước khi đối soát; không tự gửi lại với key mới.

FarmTruth Station cần receiver tương ứng ở source của dự án. Không thể chỉ đổi URL của tích hợp FlyTrust cũ sang FTA rồi coi là đã tương thích.

5. Phạm vi hiện tại

HTTP method: GET, POST, PUT, PATCH, DELETE. JSON request/response tối đa 1 MiB, timeout tối đa 60 giây, không theo redirect. Query hiện nhận scalar; dữ liệu lồng nhau đưa vào JSON body.

State hiện dùng durable JSON với một tiến trình và tối đa 4 run READY/RUNNING cùng lúc. Tăng tải hoặc nhiều replica cần thiết kế database transaction/queue riêng. OAuth refresh outbound và connector native cho giao thức khác chưa được hỗ trợ.

Kết nối dự án.Database của bạn.