feat(api): feat: add async workflow execution and history tracking

common/changes/@coze/api/fix-workflow_2025-02-24-12-00.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@coze/api",
+      "comment": "feat: add async workflow execution and history tracking",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@coze/api",
+  "email": "[email protected]"
+}

examples/coze-js-node/src/workflow.ts

@@ -48,6 +48,30 @@ async function chatWorkflow() {
   }
 }
 
+async function asyncWorkflow() {
+  assert(botId, 'botId is required');
+  assert(workflowId, 'workflowId is required');
+  const workflow = await client.workflows.runs.create({
+    workflow_id: workflowId,
+    parameters: { input: 'Hello World' },
+    is_async: true,
+  });
+  console.log('workflow', workflow);
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    const history = await client.workflows.runs.history(
+      workflowId,
+      workflow.execute_id,
+    );
+    console.log('history', history);
+    if (history[0].execute_status !== 'Running') {
+      break;
+    }
+  }
+}
+
 streamWorkflow().catch(console.error);
 nonStreamWorkflow().catch(console.error);
 chatWorkflow().catch(console.error);
+asyncWorkflow().catch(console.error);

packages/coze-js/src/resources/workflows/runs/runs.ts

@@ -39,7 +39,10 @@ export class Runs extends APIResource {
    * @param params.app_id - Optional The ID of the app.  | 可选 要进行会话聊天的 App ID
    * @returns Stream<WorkflowEvent, { id: string; event: string; data: string }> | 工作流事件流
    */
-  async *stream(params: RunWorkflowReq, options?: RequestOptions) {
+  async *stream(
+    params: Omit<RunWorkflowReq, 'is_async'>,
+    options?: RequestOptions,
+  ) {
     const apiUrl = '/v1/workflow/stream_run';
     const result = await this._client.post<
       RunWorkflowReq,
@@ -90,23 +93,44 @@ export class Runs extends APIResource {
     >(apiUrl, params, false, options);
     return response;
   }
+
+  /**
+   * Get the workflow run history | 工作流异步运行后，查看执行结果
+   * @docs zh: https://www.coze.cn/open/docs/developer_guides/workflow_history
+   * @param workflowId - Required The ID of the workflow. | 必选 工作流 ID。
+   * @param executeId - Required The ID of the workflow execution. | 必选 工作流执行 ID。
+   * @returns WorkflowExecuteHistory[] | 工作流执行历史
+   */
+  async history(
+    workflowId: string,
+    executeId: string,
+    options?: RequestOptions,
+  ) {
+    const apiUrl = `/v1/workflows/${workflowId}/run_histories/${executeId}`;
+    const response = await this._client.get<
+      undefined,
+      { data: WorkflowExecuteHistory[] }
+    >(apiUrl, undefined, false, options);
+    return response.data;
+  }
 }
 
 export interface RunWorkflowReq {
   workflow_id: string;
   bot_id?: string;
   parameters?: Record<string, unknown>;
   ext?: Record<string, string>;
-  execute_mode?: string;
-  connector_id?: string;
   app_id?: string;
+  is_async?: boolean;
 }
 
 export interface RunWorkflowData {
   data: string;
   cost: string;
   token: number;
+  msg: string;
   debug_url: string;
+  execute_id: string;
 }
 
 export interface ResumeWorkflowReq {
@@ -188,6 +212,24 @@ export interface WorkflowEventError {
   error_message: string;
 }
 
+export interface WorkflowExecuteHistory {
+  execute_id: string;
+  execute_status: 'Success' | 'Running' | 'Fail';
+  bot_id: string;
+  connector_id: string;
+  connector_uid: string;
+  run_mode: 0 | 1 | 2;
+  logid: string;
+  create_time: number;
+  update_time: number;
+  output: string;
+  token: string;
+  cost: string;
+  error_code: string;
+  error_message: string;
+  debug_url: string;
+}
+
 export class WorkflowEvent {
   // The event ID of this message in the interface response. It starts from 0.
   id: number;

packages/coze-js/test/resources/workflows.spec.ts

@@ -101,6 +101,23 @@ describe('Workflows', () => {
         expect(result).toEqual(mockResponse);
       });
     });
+
+    describe('history', () => {
+      it('should get the workflow run history', async () => {
+        const mockResponse = { data: [{ id: 'event-id' }] };
+        vi.spyOn(client, 'get').mockResolvedValue(mockResponse);
+
+        const result = await workflows.runs.history('workflow-id', 'run-id');
+
+        expect(client.get).toHaveBeenCalledWith(
+          '/v1/workflows/workflow-id/run_histories/run-id',
+          undefined,
+          false,
+          undefined,
+        );
+        expect(result).toEqual(mockResponse.data);
+      });
+    });
   });
 
   describe('Chat', () => {