Đấu nối agent và nhóm nhiều agent

Hợp đồng dùng chung cho các hệ thống có agent. Runtime API 0.3.0.

# Kết nối agent và nhóm nhiều agent với FTA

Runtime API 0.3.0: `https://api.flytrust-agent.io.vn/v1`.
Workspace: `https://flytrust-agent.io.vn/platform/`.

## 1. Chuẩn bị một lần cho mỗi hệ thống

Quản trị tạo tenant, thêm Gmail, đăng ký system/project với origin HTTPS, credential reference và các executor capabilities có thật. Kiểm tra health và bật kết nối. Tạo token OPERATOR giới hạn tenant và project, lưu trong secret của backend nguồn. Browser dùng phiên Gmail và CSRF, không dùng token backend.

Database nghiệp vụ và tiến trình agent tiếp tục ở dự án nguồn. FTA lưu danh tính agent, mô hình, instances, nhóm, kế hoạch, phê duyệt và audit. Đây là runtime một tiến trình với JSON store có khóa ghi; không chạy nhiều replica cùng ghi một volume.

## 2. Đồng bộ danh tính agent

`POST /systems/{projectId}/agents/sync`, Bearer token:

```json
{
"schemaVersion": "1.0",
"agents": [{
"externalAgentId": "content-writer",
"sourceRevision": 1,
"name": "Content Writer",
"role": "Soạn nội dung theo nhiệm vụ đã duyệt",
"goal": "Trả bản nháp và bằng chứng nguồn",
"capabilities": ["agent.task.execute"],
"executorInputs": {"agent.task.execute": {"agentId": "content-writer"}}
}]
}
```

Capability phải được quản trị đăng ký trước; manifest không cấp quyền, không thay URL hoặc secret. `executorInputs` cố định định danh agent ở executor; field phải thuộc hợp đồng capability. Caller và handoff không được ghi đè. Nếu executor dùng capability riêng cho từng agent, có thể bỏ executorInputs. `modelId` là tùy chọn, phải thuộc tenant và không thuộc agent trong system khác.

Giữ externalAgentId ổn định. sourceRevision tăng khi manifest đổi. Gửi lại cùng revision/nội dung giữ cùng FTA agent ID. Revision cũ hoặc cùng revision/nội dung khác trả 409. Agent vắng trong một lần sync vẫn được giữ. Agent mới hoặc manifest thay đổi ở trạng thái PENDING, cần quản trị cho phép trong workspace.

API trả `items[].id`. Backend nguồn lưu mapping externalAgentId → FTA agent ID. Đăng ký danh tính không tạo agent process và không chứng minh ONLINE.

## 3. Instances và heartbeat

`POST /agents/{ftaAgentId}/heartbeat`:

```json
{"instanceId":"worker-host-1","sequence":1,"state":"IDLE","timestamp":"<ISO time hiện tại>"}
```

Gửi khoảng 30 giây một lần, sequence tăng cho từng instance ID. Đồng bộ đồng hồ với server. Timestamp phải cách server không quá 120 giây. Khi process đổi, tiếp tục sequence đã lưu hoặc dùng instance ID mới. Trùng payload/sequence được ACK nhưng không làm mới receivedAt; sequence trễ hoặc xung đột trả 409. ONLINE/BUSY/ERROR cần heartbeat mới trong 120 giây; UNKNOWN là chưa có bằng chứng, STALE là bằng chứng đã cũ. Heartbeat mô tả process nguồn, không xác nhận một nhiệm vụ đã hoàn tất.

## 4. Workbench và nhiệm vụ một agent

Người dùng đăng nhập Gmail → chọn tenant → Agents → Mở Workbench. Liên kết mô hình có sẵn hoặc sửa và lưu bản nháp. Lưu tại FTA chưa chứng minh mô hình được áp dụng ở hệ thống nguồn; adapter nguồn phải có capability áp dụng cấu hình nếu dự án cần chức năng đó.

`POST /agents/{id}/runs`, header `Idempotency-Key`:

```json
{"expectedRevision":2,"mode":"LIVE","capability":"agent.task.execute","inputs":{"task":"Nhiệm vụ đã duyệt"},"expectation":{"field":"status","equals":"COMPLETED"}}
```

expectedRevision lấy từ registry hiện tại. LIVE cần semantic expectation của executor, quyền dự án và phê duyệt theo capability. DRY_RUN không gửi thao tác ra ngoài và kết quả ghi SIMULATED. Response 202 của FTA là nhận yêu cầu; poll `GET /runs/{id}` để đọc trạng thái, từng bước và kết quả xác minh. Dùng lại cùng key khi mạng lỗi; cùng key/nội dung khác trả 409.

Executor HTTPS/JSON của bản này cần trả kết quả cuối cùng trong timeout capability. API nguồn chỉ nhận job bất đồng bộ cần adapter theo dõi job đến trạng thái cuối; ACK hoặc HTTP 200/202 không tự chứng minh hoàn tất. Không gửi callbacks để tự ghi COMPLETED vào FTA. Lỗi có tác động không rõ kết quả sẽ cần đối soát, không tự thực thi lại vô hạn.

## 5. Nhóm nhiều agent

`PUT /teams/{id}` cần ít nhất hai agent ADMITTED có mô hình trong cùng tenant. Token phải có scope của mọi system thành viên. expectedRevision=0 khi tạo; cập nhật phải khớp revision hiện tại.

```json
{
"name":"Writer và Reviewer", "expectedRevision":0,
"members":[{"agentId":"<FTA writer ID>","role":"Writer"},{"agentId":"<FTA reviewer ID>","role":"Reviewer"}],
"steps":[
{"id":"draft","name":"Soạn bản nháp","agentId":"<FTA writer ID>","capability":"agent.task.execute","input":{"task":"Soạn nội dung"},"dependsOn":[],"expectation":{"field":"status","equals":"COMPLETED"}},
{"id":"review","name":"Đánh giá bản nháp","agentId":"<FTA reviewer ID>","capability":"agent.task.execute","input":{},"dependsOn":["draft"],"inputBindings":{"draft":{"stepId":"draft","field":"draft"}},"expectation":{"field":"status","equals":"COMPLETED"}}
]
}
```

`POST /teams/{id}/runs` dùng Idempotency-Key, body `{"expectedRevision":1,"mode":"LIVE","inputs":{}}`. inputs có thể ghi đè input theo step ID, trừ các field cố định của agent. Runtime thực thi tuần tự theo DAG; chưa có chạy song song. Snapshot giữ thành viên, mô hình, team revision, executor revision và agent ID của từng bước. Kết quả bước trước được truyền qua inputBindings sau khi đã xác minh. Mỗi bước có tác động được duyệt theo chính sách executor.

Thay đổi hoặc đình chỉ agent, model hoặc team làm kế hoạch cũ không được tiếp tục thực thi bước mới. Chặn nhiệm vụ tại FTA không dừng process ở nguồn. Hủy tác vụ có tác động đang chạy cần bằng chứng đối soát; không suy diễn rằng nguồn đã hủy.

## SDK backend

SDK 0.3.0 bổ sung `syncAgents`, `heartbeat`, `agents`, `teams`, `saveTeam`, `startAgentRun`, `startTeamRun`. Các API model/project/plan/run cũ vẫn giữ nguyên. Backend FTC hoặc FarmTruth cần bổ sung manifest/heartbeat từ danh sách agent thật; các mô hình đã gửi trước đây không tự chuyển thành process đang hoạt động.