API reference @cogover/sdk: Process và AI Agent

Trang này thuộc API reference của @cogover/sdk.

Process và AI Agent

processes khởi chạy Process của Cogover và agents khởi chạy lượt chạy AI Agent từ code của project. Cả hai là thành phần trong context của script và route, trigger after-change, background job và Custom Module Action. Trigger before-change bị từ chối bằng PermissionDeniedError (details.reason === "TRIGGER_READ_ONLY").

Cả hai chạy nền. start trả về ngay khi lượt chạy Process hoặc lượt chạy agent được tạo, không bao giờ đợi nó kết thúc. Để xử lý kết quả, hãy chỉ định một background job của project trong onComplete hoặc onResult: Cogover enqueue job đó khi lượt chạy kết thúc. get đọc trạng thái hiện tại của lượt chạy mà project đã khởi chạy.

Ví dụ này giả định workspace.d.ts đã khai báo Object lead và field dùng bên dưới.

import { defineJob, defineScript } from "@cogover/sdk";
import type { CogoverRecordId, ProcessCompletionJobPayload } from "@cogover/sdk";
 
export default defineScript(async ({ input, processes }) => {
  const { leadId } = input as { leadId: string };
  const { instanceId, duplicate } = await processes.start("PIXXXXXXXXXXXX", {
    input: { lead_id: leadId },
    instanceName: `Approve discount ${leadId}`,
    idempotencyKey: `discount:${leadId}`,
    onComplete: { job: "after_approval", payload: { leadId } },
  });
  return { instanceId, duplicate };
});
 
export const jobs = [
  // Payload của job là JSON: ID gửi trong onComplete.payload quay về dưới dạng chuỗi.
  defineJob<ProcessCompletionJobPayload<{ leadId: CogoverRecordId }>>({ key: "after_approval" }, async ({ payload, data }) => {
    if (payload?.payload == null || payload.process.state !== "COMPLETED") return;
    const approved = payload.process.output?.approved === true;
    await data.object("lead").records.update(payload.payload.leadId, { discount_approved: approved });
  }),
];

Quyền

Identity policy của project quyết định project được dùng những Process và AI Agent nào; quản trị viên Workspace duyệt các mục này như phần còn lại của policy. Không có mục processes thì mọi lời gọi processes ném PermissionDeniedError với details.reason là "PROCESSES_NOT_ALLOWED"; không có mục agents thì mọi lời gọi agents ném lỗi đó với "AGENTS_NOT_ALLOWED".

{
  "processes": {
    "processes": { "mode": "ONLY", "processInfoIds": ["PIXXXXXXXXXXXX"] },
    "allowSystem": false
  },
  "agents": {
    "agents": { "mode": "ALL", "agentIds": [] },
    "allowSystem": false,
    "maxRunsPerDay": 200,
    "allowAutoApprove": false
  }
}

• Lần thực thi có người dùng khởi chạy Process hoặc chạy agent dưới danh tính người dùng đó, và Cogover vẫn kiểm tra người dùng có được khởi chạy Process đó hoặc chạy agent đó không; bị từ chối thì ném PermissionDeniedError với details.reason là "PROCESS_START_DENIED" hoặc "AGENT_RUN_DENIED". Người dùng không có tài khoản Workspace không khởi chạy được Process.
• Lần thực thi không có người dùng, như job theo lịch hoặc lời gọi inbound webhook, cần allowSystem: true trong mục tương ứng. Process khởi chạy theo cách này không có người khởi tạo.
• get cũng cần có mục tương ứng, nhưng không cần được chọn: nó chỉ đọc lượt chạy mà chính project đã khởi chạy.

processes.start(processInfoId, options?): Promise<ProcessStartResult>

interface ProcessesApi {
  start(processInfoId: string, options?: ProcessStartOptions): Promise<ProcessStartResult>;
  get(instanceId: string): Promise<ProcessInstanceState>;
}
 
interface ProcessStartOptions {
  readonly input?: Record<string, unknown>;
  readonly instanceName?: string;
  readonly idempotencyKey?: string;
  readonly onComplete?: ProcessCompletion;
}
 
interface ProcessCompletion {
  readonly job: string;
  readonly payload?: unknown;
}
 
interface ProcessStartResult {
  readonly instanceId: string;
  readonly duplicate: boolean;
}

processInfoId là ID của một Process, chính là ID mà identity policy liệt kê, không phải ID của một version hay lượt chạy của nó: từ 1 đến 64 chữ cái, chữ số, _ hoặc -. Cogover khởi chạy version đã kích hoạt và đã xuất bản của Process đó, và Process phải là Process Normal flow.

Kết quả là instanceId của lượt chạy mới, và duplicate: true khi một lần start trước với cùng idempotencyKey đã trả về lượt chạy đó thay vì tạo mới. Tham số không hợp lệ ném ValidationError trước khi gửi bất cứ gì.

processes.get(instanceId): Promise<ProcessInstanceState>

interface ProcessInstanceState {
  readonly instanceId: string;
  readonly processId: string;
  readonly processInfoId: string;
  readonly state: string;
  readonly startedAt: number | null;
  readonly finishedAt: number | null;
}

state là NOT_STARTED, RUNNING, PAUSED, COMPLETED, FAILED (lượt chạy dừng vì lỗi), CANCELED hoặc DELETED. startedAt và finishedAt là Unix millisecond, hoặc null trước khi lượt chạy bắt đầu và trong lúc nó đang chạy. Lượt chạy không do project này khởi chạy ném NotFoundError.

Job nhận kết quả Process

interface ProcessCompletionJobPayload<TPayload = unknown> {
  readonly payload: TPayload | null;
  readonly process: {
    readonly instanceId: string;
    readonly processId: string;
    readonly processInfoId: string;
    readonly state: "COMPLETED" | "CANCELED" | "DELETED" | "FAILED";
    readonly output: Record<string, unknown> | null;
    readonly finishedAt: number | null;
  };
}

Khi lượt chạy được khởi chạy với onComplete kết thúc, Cogover enqueue một lần chạy của job với giá trị này làm payload: payload là onComplete.payload (hoặc null), còn process.output chứa giá trị của các biến Process được đánh dấu output, hoặc null khi không có hoặc lớn hơn 48 KiB. Xem Quy tắc của job nhận kết quả để biết job chạy thế nào.

agents.start(agentId, options): Promise<AgentStartResult>

interface AgentsApi {
  start(agentId: string, options: AgentStartOptions): Promise<AgentStartResult>;
  get<TResult = unknown>(runId: string): Promise<AgentRunState<TResult>>;
}
 
interface AgentStartOptions {
  readonly instruction: string;
  readonly variables?: Readonly<Record<string, string | number | boolean>>;
  readonly records?: readonly AgentRecordReference[];
  readonly resultSchema?: ObjectSchema<ObjectShape, false>;
  readonly runAs?: "caller" | "agent";
  readonly approvalPolicy?: "deny" | "autoApprove";
  readonly timeoutSeconds?: number;
  readonly idempotencyKey?: string;
  readonly onResult?: AgentResultCompletion;
  readonly deliverTo?: AgentDeliveryTarget;
}
 
interface AgentRecordReference {
  readonly objectSlug: string;
  readonly recordId: string;
  readonly withActivities?: boolean;
}
 
interface AgentResultCompletion {
  readonly job: string;
  readonly payload?: unknown;
}
 
interface AgentDeliveryTarget {
  readonly personnelId: string;
  readonly conversation?: "new" | "latest";
  readonly title?: string;
}
 
interface AgentStartResult {
  readonly runId: string;
  readonly duplicate: boolean;
}

const { runId } = await agents.start("AGXXXXXXXXXXXX", {
  instruction: "Classify this email as a sales or a support request.",
  variables: { subject: message.subject, body: message.body },
  records: [{ objectSlug: "lead", recordId: leadId, withActivities: true }],
  resultSchema: s.object({ category: s.enum(["sales", "support"]) }),
  idempotencyKey: `classify:${message.id}`,
  onResult: { job: "save_classification", payload: { messageId: message.id } },
});

agentId là ID của một AI Agent: từ 1 đến 64 chữ cái, chữ số, _ hoặc -. Mỗi lượt chạy làm việc trong một phiên mới của riêng nó, không người nào nhìn thấy; deliverTo là cách để lượt chạy nhắn tới một người.

Kết quả là runId của lượt chạy mới, và duplicate: true khi một lần start trước với cùng idempotencyKey đã trả về lượt chạy đó thay vì tạo mới. Tham số không hợp lệ ném ValidationError trước khi gửi bất cứ gì.

Gửi tin nhắn chat cho một nhân sự

const { runId } = await agents.start("AGXXXXXXXXXXXX", {
  instruction: "Check the overdue invoices of this account. If any are overdue, "
    + "tell the account owner which ones and what to do next.",
  records: [{ objectSlug: "account", recordId: accountId }],
  runAs: "agent",
  deliverTo: { personnelId: ownerPersonnelId, conversation: "latest", title: "Overdue invoices" },
  idempotencyKey: `overdue:${accountId}:${today}`,
  onResult: { job: "after_reminder", payload: { accountId } },
});

Với deliverTo, agent có thể chủ động mở chat với một nhân sự: tin nhắn đến hội thoại AI chat của agent đó với nhân sự đó, người nhận được thông báo như thường lệ và trả lời ngay tại đó.

• Agent tự viết tin nhắn và tự quyết định có gửi hay không, nên hãy nêu trong instruction người nhận cần biết gì và khi nào thì đáng gửi tin. Câu trả lời cuối của agent (text) và result vẫn chỉ trả về cho code của bạn; chúng không được gửi cho người nhận.
• Lượt chạy báo kết quả gửi tin trong delivery (xem agents.get). status của lượt chạy không phụ thuộc vào đó: lượt chạy có thể COMPLETED trong khi tin nhắn không được gửi.
• Người nhận phải tồn tại trong Workspace, được dùng agent và có seat AI Agent. Cogover kiểm tra khi lượt chạy bắt đầu, không đạt thì ném CogoverApiError với code là RECIPIENT_NOT_FOUND, RECIPIENT_ACCESS_DENIED hoặc RECIPIENT_AI_SEAT_REQUIRED (xem Lỗi): không có lượt chạy nào được tạo và không có gì được gửi. Identity policy không cần khai báo gì cho người nhận, và lần thực thi không có người dùng vẫn dùng được deliverTo.
• Hội thoại của người nhận tách khỏi lượt chạy. Hội thoại đó nhận tin nhắn và một ghi chú agent để lại cho chính nó về lý do nhắn. Khi người nhận trả lời, agent chạy dưới danh tính người nhận, với quyền của người nhận, không phải quyền của lượt chạy đã gửi tin.
• Cogover giới hạn số tin nhắn một agent được gửi cho một nhân sự trong một lượt chạy và trong một ngày. Tin nhắn vượt giới hạn không được gửi, và delivery báo BLOCKED với RECIPIENT_RATE_LIMITED.
• Khi phát triển local bằng Cogover Dev CLI, lượt chạy có deliverTo gửi tin nhắn thật cho người thật. Hãy dùng người nhận đã biết trước việc này.

agents.get(runId): Promise<AgentRunState>

interface AgentRunState<TResult = unknown> {
  readonly runId: string;
  readonly status: string;
  readonly text: string | null;
  readonly result: TResult | null;
  readonly error: { readonly code: string; readonly message: string } | null;
  readonly delivery: AgentDelivery | null;
}
 
interface AgentDelivery {
  readonly status: "SENT" | "NOT_SENT" | "BLOCKED" | "FAILED";
  readonly errorCode: string | null;
  readonly chatSessionId: string | null;
  readonly conversationId: string | null;
  readonly newConversation: boolean;
}

status là QUEUED hoặc RUNNING khi lượt chạy đang diễn ra, sau đó là trạng thái cuối như COMPLETED, FAILED, TIMEOUT hoặc CANCELLED. text là câu trả lời của agent (tối đa 32 KiB), result là kết quả có cấu trúc khớp resultSchema, và error là lý do lượt chạy thất bại; mỗi giá trị là null khi không có. error.code là một trong RESULT_SCHEMA_MISMATCH, TIMEOUT, CALLER_TIMEOUT, CANCELLED, MAX_TURNS, GUARDRAIL_REJECTED, APPROVAL_DENIED, SERVER_RESTARTED, SESSION_BUSY, SESSION_EVICTED, AGENT_INACTIVE, AGENT_ACCESS_DENIED, AGENT_CONFIG_INVALID, CONFIG_LOAD_FAILED, LLM_HTTP_ERROR, LLM_NETWORK, LLM_RESPONSE_FAILED, LLM_PARSE, OUTPUT_TRUNCATED, INTERNAL_ERROR, một trong các mã tính phí credit AI INSUFFICIENT_CREDITS, AI_SUBSCRIPTION_REQUIRED, AI_SEAT_REQUIRED, AGENT_CREDIT_LIMIT_EXCEEDED, MODEL_NOT_PRICED (ý nghĩa như ở Lỗi) khi lượt chạy bị dừng vì tính phí, hoặc AGENT_ERROR với mọi lý do khác, và error.message là mô tả tiếng Anh cố định của mã đó: nội dung từ nhà cung cấp mô hình AI không bao giờ được chuyển tiếp. Job onResult nhận cùng error đó. Lượt chạy không do project này khởi chạy ném NotFoundError.

delivery là kết quả của deliverTo, và là null với lượt chạy được khởi chạy không có tuỳ chọn này. Hãy đọc nó khi lượt chạy đã có trạng thái cuối: khi lượt chạy còn đang diễn ra, giá trị này chưa phải kết quả cuối và có thể vẫn là null. Job onResult nhận cùng giá trị đó.

delivery.errorCode là null với SENT và NOT_SENT. Ngược lại nó là một trong:

chatSessionId và conversationId là null trừ khi đã có tin nhắn được gửi.

Job nhận kết quả AI Agent

interface AgentResultJobPayload<TPayload = unknown, TResult = unknown> {
  readonly payload: TPayload | null;
  readonly agentRun: {
    readonly runId: string;
    readonly status: string;
    readonly text: string | null;
    readonly result: TResult | null;
    readonly error: { readonly code: string; readonly message: string } | null;
    readonly usage: Record<string, unknown> | null;
    readonly delivery: AgentDelivery | null;
  };
}

Khi lượt chạy được khởi chạy với onResult kết thúc, Cogover enqueue một lần chạy của job với giá trị này làm payload: payload là onResult.payload (hoặc null), agentRun.text bị cắt còn 32 KiB, agentRun.result là null khi lớn hơn 16 KiB, agentRun.usage cho biết inputTokens, outputTokens, iterations và durationMs, và agentRun.delivery là kết quả của deliverTo đúng như agents.get trả về (null với lượt chạy được khởi chạy không có tuỳ chọn này).

defineJob<AgentResultJobPayload<{ accountId: string }>>({ key: "after_reminder" }, async ({ payload, log }) => {
  const delivery = payload?.agentRun.delivery;
  if (delivery?.status === "SENT") {
    log.info("Owner reminded", { conversationId: delivery.conversationId });
  } else if (delivery !== null && delivery !== undefined && delivery.status !== "NOT_SENT") {
    log.warn("Reminder not delivered", { status: delivery.status, errorCode: delivery.errorCode });
  }
});

Quy tắc của job nhận kết quả

• Job được chỉ định trong onComplete hoặc onResult chạy như mọi job được enqueue (xem Quy tắc thực thi job): job.source là "enqueue", job được giao ít nhất một lần và được thử lại khi ném RetryableError. Lịch sử lần chạy ghi job với enqueuedBy là process:<instanceId> hoặc agent:<runId>.
• Job chạy dưới danh tính người dùng của lần thực thi đã gọi start (hoặc không có người dùng khi lần thực thi đó không có). Job nhận ít hơn lần thực thi đó hai bước ngân sách tự động hoá (một bước để tới Process hoặc agent, một bước để quay về), và tiếp nối chuỗi job của lần thực thi đó, nên job mà Process hoặc agent của nó kết thúc bằng việc khởi chạy lại chính job đó sẽ dừng như job tự enqueue chính nó. Khi không còn bước nào, hoặc chuỗi quá dài, kết quả sẽ không được giao.
• Job phải được version đang active khai báo khi gọi start; nếu không, start ném ValidationError. Nếu khi lượt chạy kết thúc mà version đang active không còn khai báo job, hoặc project đã có 10.000 lần chạy job đang chờ, kết quả sẽ không được giao.

Idempotency và thử lại

• Không có idempotencyKey thì mỗi lần start tạo một lượt chạy mới.
• Có key thì lần start thứ hai với cùng key trong cùng project trả về lượt chạy đầu tiên với duplicate: true. Cogover giữ key trong lúc lượt chạy còn hoạt động và 7 ngày sau khi nó kết thúc. Dùng lại key cho một Process hoặc agent khác sẽ ném ValidationError. Key thuộc về danh tính đã dùng nó đầu tiên: người dùng khác của project, hoặc lần thực thi không có người dùng, gửi cùng key sẽ nhận CogoverApiError với code: "IDEMPOTENCY_CONFLICT", không bao giờ nhận lượt chạy của danh tính kia. Hãy đưa người dùng vào key khi nhiều người có thể dùng chung key.
• Key chỉ định lượt chạy đầu tiên, bất kể các tuỳ chọn khác của nó: lần agents.start thứ hai với cùng key nhưng deliverTo khác trả về lượt chạy đầu tiên với duplicate: true và không gửi gì cho người nhận kia. Hãy đưa người nhận vào key khi một công việc nhắn cho nhiều người.
• RetryableError báo lỗi tạm thời. Khi details.writesMayHaveCompleted là false, chưa có gì được khởi chạy. Khi giá trị này là true, lượt chạy có thể đã được tạo: hãy thử lại sau với cùng idempotencyKey, Cogover sẽ hoàn tất lần start đó thay vì tạo lượt chạy thứ hai; lần thử lại quá sớm có thể lại ném RetryableError. Sau một lần từ chối dứt khoát, như ValidationError, PermissionDeniedError, một mã tính phí credit AI hoặc một mã về người nhận của deliverTo, key được dùng lại.
• Trong job, key suy ra từ payload của job hoặc job.id, và trong action, key suy ra từ action.runId, giúp handler được thử lại không khởi chạy cùng một việc hai lần.

Giới hạn

• Mỗi lời gọi processes và agents là một capability call (xem Giới hạn của một lần thực thi).
• Một lần thực thi gọi processes.start tối đa 20 lần và agents.start tối đa 5 lần. Vượt quá sẽ ném RateLimitError không có details.budget.
• agents.start còn được tính vào maxRunsPerDay của identity policy, và dịch vụ AI Agent có thể áp quota riêng; cả hai đều ném RateLimitError. Một project còn được khởi chạy tối đa 1.000 Process trong một ngày UTC. Lần start bị dịch vụ Process hoặc AI Agent từ chối không bị tính.
• Khởi chạy một Process hoặc một lượt chạy AI Agent dùng một bước của ngân sách tự động hoá, chính ngân sách giới hạn chuỗi record trigger. Khi không còn bước nào, start ném CogoverApiError với code: "MAX_HOP_EXCEEDED".
• Các AI Agent khởi chạy lẫn nhau, qua action hoặc qua job nhận kết quả, được lồng tối đa 3 cấp; sâu thêm một cấp thì agents.start ném CogoverApiError với code: "AGENT_DEPTH_EXCEEDED".
• Action "read" và phiên phát triển local chỉ đọc được gọi get nhưng không được gọi start: start ném PermissionDeniedError.
• Cogover giới hạn số tin nhắn một lượt chạy được gửi cho người nhận của deliverTo, trong lượt chạy và trong một ngày (xem Gửi tin nhắn chat cho một nhân sự).

Lỗi

Năm mã tính phí credit AI (từ INSUFFICIENT_CREDITS tới MODEL_NOT_PRICED) chỉ do agents.start ném, khi dịch vụ AI Agent từ chối lượt chạy: không có lượt chạy nào được tạo, details.upstreamCode giữ cùng mã và details.writesMayHaveCompleted là false. Hãy báo người dùng việc cần làm (nạp thêm credit, đăng ký gói, gán seat, nâng hạn mức của agent hoặc chọn model khác) thay vì thử lại ngay. Lượt chạy đã bắt đầu mà bị dừng vì cùng lý do sẽ kết thúc với error.code là mã đó.

Bốn mã về người nhận (từ RECIPIENT_NOT_FOUND tới DELIVERY_UNAVAILABLE) chỉ do agents.start có deliverTo ném: không có lượt chạy nào được tạo, không có gì được gửi, và details.upstreamCode giữ cùng mã. Các mã này nói về người nhận, không bao giờ về người dùng của lần thực thi; lỗi của chính người dùng đó là AI_SEAT_REQUIRED và PermissionDeniedError với AGENT_RUN_DENIED. DELIVERY_UNAVAILABLE là lỗi tạm thời, nên thử lại sau; ba mã còn lại cần thay đổi trong Workspace trước. Khi cùng vấn đề đó chỉ xuất hiện lúc lượt chạy đang gửi tin, lượt chạy vẫn kết thúc bình thường và delivery.errorCode giữ mã đó.

Phát triển local

Khi code chạy local bằng Cogover Dev CLI, start tạo lượt chạy Process và lượt chạy agent thật, dưới danh tính người dùng của Project key, và phiên chỉ đọc sẽ từ chối lời gọi này. Lượt chạy có deliverTo gửi tin nhắn chat thật cho người nhận, đúng như version đã publish. onComplete và onResult bị từ chối bằng CogoverApiError code: "NOT_SUPPORTED", vì job của chúng chỉ chạy trong version đã publish: hãy thử lần start mà không có hai tuỳ chọn này và đọc kết quả bằng get, rồi publish project để thử job.