挂起任务多 Agent 工作流

一、快速开始

                🎯 用途：本文档定义了挂起任务多 Agent 系统的完整 API 接口，供各 Agent 直接调用。
            

Base URL

BASE_URL = "https://api.pending-task.system/v1"

认证方式

类型	Header	说明
API Key	`Authorization: Bearer {api_key}`	每个 Agent 分配独立 API Key
Agent ID	`X-Agent-ID: {agent_id}`	标识调用方 Agent
Request ID	`X-Request-ID: {uuid}`	用于链路追踪

核心流程（6 步）

POST /tasks/{id}/start → Orchestrator 接收任务 GET /tasks/{id}/status → 查询任务状态 POST /contact/initiate → Contact Agent 联系用户 POST /triage/classify → Triage Agent 意图识别 POST /actions/execute → Action Agent 执行动作 POST /audit/log → Audit Agent 记录日志

二、系统架构

┌──────────────────────────────────────────────────────────────────────────────┐ │ API Gateway (入口层) │ │ 认证 / 限流 / 路由 / 日志 / 监控 │ └─────────────────────────────────┬────────────────────────────────────────────┘ │ ┌─────────────────────────┼─────────────────────────┐ ↓ ↓ ↓ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │ Orchestrator API │ │ Agent Runtime │ │ State Machine │ │ /tasks/* │ │ /agents/* │ │ /states/* │ │ │ │ │ │ │ │ · 任务接收 │ │ · Agent 注册 │ │ · 状态查询 │ │ · 任务分发 │ │ · 心跳检测 │ │ · 状态转换 │ │ · 进度追踪 │ │ · 负载均衡 │ │ · 状态持久化 │ └───────────────────┘ └───────────────────┘ └───────────────────┘ ↓ ↓ ↓ ┌──────────────────────────────────────────────────────────────────────────────┐ │ Tool Layer (工具层) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Contact │ │ Triage │ │ Action │ │ Audit │ │ │ │ Tools │ │ Tools │ │ Tools │ │ Tools │ │ │ │ │ │ │ │ │ │ │ │ │ │ · call_user │ │ · classify │ │ · update │ │ · log │ │ │ │ · send_sms │ │ · validate │ │ · notify │ │ · alert │ │ │ │ · send_im │ │ · confidence│ │ · cancel │ │ · report │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └──────────────────────────────────────────────────────────────────────────────┘ │ ↓ ┌──────────────────────────────────────────────────────────────────────────────┐ │ Data Layer (数据层) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Task DB │ │ State DB │ │ Log DB │ │ Config DB │ │ │ │ (PostgreSQL)│ │ (Redis) │ │ (Elastic) │ │ (YAML) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └──────────────────────────────────────────────────────────────────────────────┘

三、状态机定义

状态枚举

enum TaskState {
    # 初始状态
    PENDING = "pending"              # 挂起中，等待处理
    
    # 联系阶段
    CONTACTING = "contacting"        # 正在联系用户
    RESPONDED = "responded"          # 用户已响应
    NO_RESPONSE = "no_response"      # 用户未响应
    
    # 处理阶段
    CLASSIFIED = "classified"        # 意图已分类
    ACTION_TAKEN = "action_taken"    # 动作已执行
    WAITING_FOLLOWUP = "waiting_followup"  # 等待跟进
    
    # 结束状态
    CLOSED = "closed"              # 已关闭
}

状态转换规则

当前状态	触发事件	下一状态	校验规则
`PENDING`	`task.start`	`CONTACTING`	联系次数<4
`CONTACTING`	`user.responded`	`RESPONDED`	—
`CONTACTING`	`user.no_answer`	`NO_RESPONSE`	—
`NO_RESPONSE`	`contact.retry`	`CONTACTING`	联系次数<4
`NO_RESPONSE`	`contact.max_reached`	`CLOSED`	联系次数=4
`RESPONDED`	`triage.complete`	`CLASSIFIED`	置信度>60%
`CLASSIFIED`	`action.execute`	`ACTION_TAKEN`	权限校验通过
`ACTION_TAKEN`	`intent=暂缓`	`WAITING_FOLLOWUP`	—
`ACTION_TAKEN`	`intent=继续/终止`	`CLOSED`	—
`WAITING_FOLLOWUP`	`followup.time_reached`	`CONTACTING`	跟进时间已到

状态转换 API

POST /states/transition

描述：执行状态转换

# Request
{
    "task_id": "HT20260313001",
    "from_state": "pending",
    "to_state": "contacting",
    "event": "task.start",
    "agent_id": "orchestrator",
    "metadata": {
        "contact_count": 1,
        "timestamp": "2026-03-13T21:00:00Z"
    }
}

# Response 200 OK
{
    "success": true,
    "task_id": "HT20260313001",
    "previous_state": "pending",
    "current_state": "contacting",
    "transition_id": "txn_abc123"
}

四、Agent 接口

1️⃣ Orchestrator Agent API

POST /agents/orchestrator/tasks/start

描述：接收新挂起任务，初始化处理流程

# Request
{
    "task_id": "HT20260313001",
    "order_id": "SO20260313001",
    "order_type": "未上门",
    "contact_count": 0,
    "last_contact_time": null,
    "metadata": {
        "customer_id": "CUST001",
        "phone": "138****0000",
        "pending_reason": "用户要求改约"
    }
}

# Response 200 OK
{
    "success": true,
    "task_id": "HT20260313001",
    "status": "contacting",
    "next_action": "contact_user",
    "assigned_agent": "contact_agent"
}

GET /agents/orchestrator/tasks/{task_id}/status

描述：查询任务当前状态和处理进度

# Response 200 OK
{
    "task_id": "HT20260313001",
    "status": "classified",
    "progress": {
        "contact_count": 2,
        "max_contacts": 4,
        "last_contact_result": "responded",
        "user_intent": "暂不推进",
        "confidence": 0.92
    },
    "next_action": "schedule_followup",
    "created_at": "2026-03-13T21:00:00Z",
    "updated_at": "2026-03-13T21:05:00Z"
}

POST /agents/orchestrator/tasks/dispatch

描述：分发动作到指定 Agent

# Request
{
    "task_id": "HT20260313001",
    "target_agent": "action_agent",
    "action_type": "schedule_followup",
    "action_params": {
        "followup_date": "2026-03-16T10:00:00Z",
        "reason": "用户配件未到"
    }
}

# Response 200 OK
{
    "success": true,
    "dispatch_id": "disp_xyz789",
    "target_agent": "action_agent",
    "status": "dispatched"
}

2️⃣ Contact Agent API

POST /agents/contact/initiate

描述：发起用户联系（电话/短信/IM）

# Request
{
    "task_id": "HT20260313001",
    "contact_method": "phone",
    "phone_number": "138****0000",
    "script_id": "pending_task_v1",
    "attempt": 1
}

# Response 200 OK
{
    "success": true,
    "contact_id": "CONT001",
    "result": "answered",
    "duration_seconds": 120,
    "recording_url": "https://...",
    "transcript": "用户表示配件未到..."
}

POST /agents/contact/result/record

描述：记录联系结果

# Request
{
    "contact_id": "CONT001",
    "task_id": "HT20260313001",
    "result": "answered",
    "user_feedback": "配件未到，等配件到了再约",
    "raw_transcript": "...",
    "contact_time": "2026-03-13T21:05:00Z"
}

# Response 200 OK
{
    "success": true,
    "recorded": true,
    "next_step": "triage_classify"
}

3️⃣ Triage Agent API

POST /agents/triage/classify

描述：识别用户意图，归类为 4 类状态

# Request
{
    "task_id": "HT20260313001",
    "user_input": "配件还没到，等配件到了再说",
    "context": {
        "order_type": "未上门",
        "pending_reason": "用户要求改约",
        "contact_count": 1
    }
}

# Response 200 OK
{
    "success": true,
    "classification": {
        "level1_intent": "暂缓",
        "level2_intent": "配件未到",
        "confidence": 0.95,
        "requires_human_review": false
    },
    "suggested_action": "schedule_followup",
    "followup_days": 3
}

4️⃣ Action Agent API

POST /agents/actions/execute

描述：执行系统动作（改约/通知/取消等）

# Request
{
    "task_id": "HT20260313001",
    "action_type": "schedule_followup",
    "action_params": {
        "followup_date": "2026-03-16T10:00:00Z",
        "reason": "配件未到"
    },
    "requires_approval": false
}

# Response 200 OK
{
    "success": true,
    "action_id": "ACT001",
    "status": "executed",
    "result": {
        "followup_scheduled": true,
        "followup_id": "FU20260316001"
    }
}

5️⃣ Audit Agent API

POST /agents/audit/log

描述：记录全流程审计日志

# Request
{
    "task_id": "HT20260313001",
    "event_type": "action_executed",
    "agent_id": "action_agent",
    "action": "schedule_followup",
    "timestamp": "2026-03-13T21:10:00Z",
    "metadata": {
        "previous_state": "classified",
        "new_state": "waiting_followup",
        "confidence": 0.95,
        "approval_required": false
    }
}

# Response 200 OK
{
    "success": true,
    "log_id": "LOG20260313001",
    "stored": true
}

POST /agents/audit/alert

描述：触发告警（异常拦截）

# Request
{
    "alert_type": "low_confidence",
    "task_id": "HT20260313001",
    "severity": "warning",
    "message": "意图识别置信度低于 60%",
    "metadata": {
        "confidence": 0.45,
        "classified_intent": "暂缓"
    }
}

# Response 200 OK
{
    "success": true,
    "alert_id": "ALT001",
    "escalated_to": "quality_inspector",
    "status": "pending_review"
}

五、工具调用协议

工具调用标准格式

# 工具调用请求
{
    "tool_name": "contact_user",
    "tool_version": "1.0",
    "input": {
        "task_id": "HT20260313001",
        "phone": "138****0000",
        "script": "pending_task_v1"
    },
    "timeout_ms": 30000,
    "retry_policy": {
        "max_retries": 2,
        "retry_delay_ms": 1000
    }
}

# 工具调用响应
{
    "success": true,
    "output": {
        "contact_result": "answered",
        "duration": 120,
        "transcript": "..."
    },
    "execution_time_ms": 5230
}

可用工具列表

工具名	所属 Agent	功能	超时
`contact_user`	Contact	电话联系用户	30s
`send_sms`	Contact	发送短信	5s
`send_im`	Contact	发送 IM 消息	5s
`classify_intent`	Triage	意图识别	2s
`validate_classification`	Triage	分类校验	1s
`update_appointment`	Action	修改预约	5s
`notify_engineer`	Action	通知工程师	3s
`cancel_order`	Action	取消订单	5s
`schedule_followup`	Action	安排跟进	2s
`log_event`	Audit	记录日志	1s
`trigger_alert`	Audit	触发告警	1s
`generate_report`	Audit	生成报告	10s

六、工作流编排

标准工作流（BPMN 格式）

workflow PendingTaskWorkflow {
    version: "1.0"
    trigger: "task.created"
    
    steps: [
        {
            id: "step1_receive",
            agent: "orchestrator",
            action: "receive_task",
            next: "step2_validate"
        },
        {
            id: "step2_validate",
            agent: "orchestrator",
            action: "validate_task",
            next: "step3_contact",
            on_error: "escalate_human"
        },
        {
            id: "step3_contact",
            agent: "contact_agent",
            action: "initiate_contact",
            next: "step4_check_response"
        },
        {
            id: "step4_check_response",
            type: "gateway",
            condition: "contact_result == 'answered'",
            next: "step5_triage",
            else: "step4_retry_contact"
        },
        {
            id: "step5_triage",
            agent: "triage_agent",
            action: "classify_intent",
            next: "step6_check_confidence"
        },
        {
            id: "step6_check_confidence",
            type: "gateway",
            condition: "confidence >= 0.8",
            next: "step7_execute",
            else: "step6_human_review"
        },
        {
            id: "step7_execute",
            agent: "action_agent",
            action: "execute_action",
            next: "step8_audit"
        },
        {
            id: "step8_audit",
            agent: "audit_agent",
            action: "log_and_close",
            next: "end"
        }
    ]
}

工作流状态图

[开始] ↓ [Orchestrator 接收任务] ↓ [任务预校验] ──失败──→ [升级人工] ↓ 成功 [Contact Agent 联系用户] ↓ {是否接通？} ├─未接通─→ [联系次数<4?] ──是──→ [再次联系] │ └─否──→ [联系失败完结] └─已接通─→ [Triage Agent 意图识别] ↓ {置信度≥80%?} ├─是─→ [Action Agent 执行动作] │ ↓ │ [Audit Agent 记录] │ ↓ │ [结束] └─否─→ [人工复核] ↓ [重新分类] ↓ [返回执行]

七、调用示例

完整流程调用示例

# 1. Orchestrator 接收任务
curl -X POST https://api.pending-task.system/v1/agents/orchestrator/tasks/start \
  -H "Authorization: Bearer {orchestrator_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "HT20260313001",
    "order_id": "SO20260313001",
    "order_type": "未上门",
    "contact_count": 0,
    "metadata": {
        "customer_id": "CUST001",
        "phone": "138****0000"
    }
}'

# 2. Contact Agent 联系用户
curl -X POST https://api.pending-task.system/v1/agents/contact/initiate \
  -H "Authorization: Bearer {contact_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "HT20260313001",
    "contact_method": "phone",
    "phone_number": "138****0000",
    "script_id": "pending_task_v1",
    "attempt": 1
}'

# 3. Triage Agent 意图识别
curl -X POST https://api.pending-task.system/v1/agents/triage/classify \
  -H "Authorization: Bearer {triage_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "HT20260313001",
    "user_input": "配件还没到，等配件到了再说",
    "context": {
        "order_type": "未上门",
        "contact_count": 1
    }
}'

# 4. Action Agent 执行动作
curl -X POST https://api.pending-task.system/v1/agents/actions/execute \
  -H "Authorization: Bearer {action_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "HT20260313001",
    "action_type": "schedule_followup",
    "action_params": {
        "followup_date": "2026-03-16T10:00:00Z",
        "reason": "配件未到"
    },
    "requires_approval": false
}'

# 5. Audit Agent 记录日志
curl -X POST https://api.pending-task.system/v1/agents/audit/log \
  -H "Authorization: Bearer {audit_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "HT20260313001",
    "event_type": "task_completed",
    "agent_id": "action_agent",
    "action": "schedule_followup",
    "timestamp": "2026-03-13T21:10:00Z",
    "metadata": {
        "final_state": "waiting_followup",
        "confidence": 0.95
    }
}'

八、数据表结构

任务主表（tasks）

CREATE TABLE tasks (
    task_id          VARCHAR(32) PRIMARY KEY,
    order_id         VARCHAR(32) NOT NULL,
    order_type       VARCHAR(16) NOT NULL,  # 未上门/已上门
    status           VARCHAR(32) NOT NULL,  # 8 种状态
    contact_count    INTEGER DEFAULT 0,
    max_contacts     INTEGER DEFAULT 4,
    last_contact_time TIMESTAMP,
    next_contact_time TIMESTAMP,
    user_intent_l1   VARCHAR(16),           # 4 类一级意图
    user_intent_l2   VARCHAR(32),           # 6 类二级意图
    confidence       DECIMAL(3,2),
    created_at       TIMESTAMP DEFAULT NOW(),
    updated_at       TIMESTAMP DEFAULT NOW(),
    finished_at      TIMESTAMP,
    finish_reason    VARCHAR(32),
    metadata         JSONB
);

联系记录表（contact_logs）

CREATE TABLE contact_logs (
    contact_id       VARCHAR(32) PRIMARY KEY,
    task_id          VARCHAR(32) NOT NULL,
    contact_method   VARCHAR(16) NOT NULL,  # phone/sms/im
    contact_result   VARCHAR(16) NOT NULL,  # answered/no_answer
    duration_seconds INTEGER,
    transcript       TEXT,
    recording_url    VARCHAR(255),
    contact_time     TIMESTAMP NOT NULL,
    created_at       TIMESTAMP DEFAULT NOW(),
    FOREIGN KEY (task_id) REFERENCES tasks(task_id)
);

审计日志表（audit_logs）

CREATE TABLE audit_logs (
    log_id           VARCHAR(32) PRIMARY KEY,
    task_id          VARCHAR(32) NOT NULL,
    event_type       VARCHAR(32) NOT NULL,
    agent_id         VARCHAR(32) NOT NULL,
    action           VARCHAR(32),
    timestamp        TIMESTAMP NOT NULL,
    metadata         JSONB,
    created_at       TIMESTAMP DEFAULT NOW(),
    FOREIGN KEY (task_id) REFERENCES tasks(task_id)
);

# 创建索引加速查询
CREATE INDEX idx_audit_task_id ON audit_logs(task_id);
CREATE INDEX idx_audit_timestamp ON audit_logs(timestamp);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_next_contact ON tasks(next_contact_time);

九、错误码表

错误码	错误名	说明	处理建议
`200`	SUCCESS	成功	—
`400`	BAD_REQUEST	请求参数错误	检查请求参数
`401`	UNAUTHORIZED	认证失败	检查 API Key
`403`	FORBIDDEN	权限不足	检查 Agent 权限
`404`	NOT_FOUND	任务不存在	检查 task_id
`409`	STATE_CONFLICT	状态转换冲突	检查当前状态
`422`	VALIDATION_FAILED	数据校验失败	检查数据格式
`429`	RATE_LIMITED	请求频率超限	等待后重试
`500`	INTERNAL_ERROR	系统内部错误	联系技术支持
`503`	SERVICE_UNAVAILABLE	服务不可用	稍后重试

错误响应格式

{
    "success": false,
    "error": {
        "code": "STATE_CONFLICT",
        "message": "Cannot transition from 'closed' to 'contacting'",
        "details": {
            "current_state": "closed",
            "requested_state": "contacting",
            "allowed_transitions": []
        }
    },
    "request_id": "req_abc123",
    "timestamp": "2026-03-13T21:15:00Z"
}

十、监控指标

核心监控指标

指标名	类型	说明	告警阈值
`task.processing_time`	Histogram	任务处理时长	P95>5min
`task.success_rate`	Gauge	任务成功率	<90%
`contact.answer_rate`	Gauge	用户接通率	<30%
`triage.confidence_avg`	Gauge	平均置信度	<0.7
`action.auto_execute_rate`	Gauge	自动执行率	<80%
`audit.alert_count`	Counter	告警数量	>10/hour
`agent.error_rate`	Gauge	Agent 错误率	>5%
`api.latency_p95`	Histogram	API P95 延迟	>500ms

Prometheus 指标示例

# 任务处理时长
histogram_quantile(0.95, rate(task_processing_time_bucket[5m]))

# 任务成功率
rate(task_success_total[5m]) / rate(task_total[5m])

# 用户接通率
rate(contact_answered_total[5m]) / rate(contact_attempt_total[5m])

# 意图识别平均置信度
avg(triage_confidence) by (intent_level1)

# Agent 错误率
rate(agent_error_total[5m]) / rate(agent_request_total[5m])

# API 延迟 P95
histogram_quantile(0.95, rate(api_request_duration_bucket[5m]))

Grafana 仪表盘建议

📊 任务概览

任务总数
处理中任务
今日完成数
平均处理时长

📈 趋势图表

任务量趋势（7 天）
成功率趋势
接通率趋势
置信度趋势

⚠️ 告警面板

当前活跃告警
今日告警数
告警处理率
升级工单数