小程序开放平台

文档中心
平台概述

queryTasks

更新时间:2025-10-31 14:50:05

queryTasks

方法概述

queryTasks
用于查询多模态模型「文生图」等异步任务的状态和结果。该方法支持轮询机制,可以实时获取任务的执行进度和最终结果。

基本信息

  1. 函数签名
    queryTasks(params: QueryTasksParams): Promise<QueryTasksResult>
  2. 服务 URI
    GET
    /v1/aiagent/agents/:agentId/query-tasks
  3. 返回类型
    Promise<QueryTasksResult>
    - 异步方法,返回任务查询结果
  4. 调用方式 内部方法,由 AgentRuntime 框架提供

功能说明

  • 任务状态查询:实时获取异步任务的执行状态
  • 结果获取:当任务完成时,获取任务的输出结果
  • 轮询支持:支持定时轮询机制,自动检查任务状态
  • 多模态支持:主要用于文生图等异步任务的结果查询

参数说明

QueryTasksParams 参数数据结构:

字段
类型
描述
是否必传
最低支持版本
taskIdstring任务id文生图: 0.3.0, 其他任务: < 0.3.0

参数详细说明

taskId 字段

  • 类型:字符串
  • 作用:唯一标识一个异步任务
  • 来源:通常由创建任务时返回的任务ID
  • 示例
    "task_1234567890abcdef"

返回值说明

QueryTasksResult 返回数据结构:

字段
类型
描述
最低支持版本
request_idstring请求id文生图: 0.3.0, 其他任务: < 0.3.0
output见下方代码块任务输出信息文生图: 0.3.0, 其他任务: < 0.3.0
usage
{ image_count?: number }
输出信息文生图: 0.3.0, 其他任务: < 0.3.0

output 字段详细说明

/** 任务输出信息 */
output: {
    task_id: string;
    task_status: "PENDING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "CANCELED" | "UNKNOWN";
    results?: Array<{
        url?: string;
        [key: string]: any;
    }>;
    task_metrics?: {
        TOTAL: number;
        SUCCEEDED: number;
        FAILED: number;
    };
};

task_status 状态说明

  • PENDING:任务等待执行
  • RUNNING:任务正在执行中
  • SUCCEEDED:任务执行成功
  • FAILED:任务执行失败
  • CANCELED:任务被取消
  • UNKNOWN:任务状态未知

使用示例

基础查询示例

const agent = this.getAgent();
if (!agent) return;

const taskInfo = await agent.queryTasks({ taskId: "task_1234567890abcdef" });
console.log("任务信息:", taskInfo);

轮询查询示例

// 轮询任务状态
this.pollingTimers[taskId] = setInterval(async () => {
    this.pollingCounts[taskId]++;
    console.log(
        `轮询第${this.pollingCounts[taskId]}次,任务ID: ${taskId},图片索引: ${imageIndex}`
    );

    try {
        const result = await agent.queryTasks({ taskId });
        console.log(`taskId: ${taskId} 轮询结果:`, result);

        // 根据任务状态处理结果
        if (this.handleTaskResult(result, taskId, imageIndex)) {
            // 任务完成,停止轮询
            console.log(`taskId: ${taskId} 任务完成,停止轮询`);
            this.clearPollingTimer(taskId);
            return;
        }

        // 检查是否超过最大轮询次数
        if (this.pollingCounts[taskId] >= this.maxPollingCount) {
            console.warn(`taskId: ${taskId} 轮询超时,停止轮询`);
            this.clearPollingTimer(taskId);
            this.handlePollingTimeout(taskId, imageIndex);
            return;
        }
    } catch (error) {
        console.error(`taskId: ${taskId} 轮询请求失败:`, error);
        this.pollingCounts[taskId]++;

        // 连续失败3次则停止轮询
        if (this.pollingCounts[taskId] >= 3) {
            console.error(`taskId: ${taskId} 轮询连续失败,停止轮询`);
            this.clearPollingTimer(taskId);
            this.handlePollingError(error, taskId, imageIndex);
            return;
        }
    }
}, 3000); // 3秒轮询一次

注意事项

⚠️ 重要提醒

  1. 轮询频率:建议轮询间隔不少于3秒,避免过于频繁的请求
  2. 超时处理:设置合理的最大轮询次数,避免无限轮询
  3. 错误处理:建议添加 try-catch 块处理网络异常和业务异常
  4. 资源清理:轮询结束后及时清理定时器,避免内存泄漏