chenchen/pingtai_agent

Fork 1

Files

T

zhanggangyong 387c80b901 更新智能体

2026-02-21 03:00:16 +00:00

11 KiB

Raw Permalink Blame History

意图澄清 Agent

本 Agent 提供 意图澄清与输入补全 能力，通过 HTTP API 与 MCP（Model Context Protocol） 对外提供服务。

核心能力：

意图澄清：将模糊输入转化为清晰可执行的指令
指令扩展：将简短指令展开为详细执行步骤
参数推断：从自然语言中提取结构化参数
批量处理：一次性处理多条模糊输入

功能概览

提供人类输入的 语义理解、缺失补全、意图推断、参数提取 能力，返回结构化的可执行指令。

支持能力：

识别输入中的缺失信息
基于上下文推断合理默认值
补全为完整可执行指令
标注不确定性与假设

1⃣ clarify_intent — 意图澄清

功能说明

将模糊、不完整的用户输入澄清为 清晰、完整、可执行 的指令，识别缺失要素并补全。

REST API 调用

POST /api/v1/clarify
Content-Type: application/json
api-key: {your-api-key}

{
  "user_input": "帮我写个接口",
  "context": "正在开发一个用户管理系统",
  "domain": "后端开发"
}

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "clarify_intent",
    "arguments": {
      "user_input": "帮我写个接口",
      "context": "正在开发一个用户管理系统",
      "domain": "后端开发"
    }
  }
}

参数说明

参数	类型	必需	默认值	说明
user_input	string	✅	-	用户的原始输入（可能模糊、不完整）
context	string	❌	null	上下文信息（如之前的对话、当前任务背景）
domain	string	❌	null	领域说明（如"编程"、"写作"、"数据分析"）

返回结果

{
  "success": true,
  "original_input": "帮我写个接口",
  "analysis": {
    "core_intent": "请求编写 API 接口",
    "missing_elements": ["接口功能", "接口路径", "请求方法", "返回格式"],
    "ambiguous_parts": ["'接口'具体指 REST API 还是其他类型"],
    "assumptions": ["假设是 REST API", "假设使用 JSON 格式", "基于上下文推断是用户相关接口"]
  },
  "clarified_intent": {
    "full_instruction": "请使用 Python FastAPI 框架编写一个用户管理 REST API 接口，包含用户 CRUD 操作，使用 JSON 格式进行数据交换，需要包含请求参数验证和错误处理",
    "action": "编写",
    "target": "用户管理 REST API 接口",
    "constraints": ["使用 FastAPI 框架", "JSON 数据格式", "包含参数验证"],
    "expected_output": "可运行的 Python API 代码"
  },
  "confidence": "medium",
  "clarification_needed": ["需要支持哪些具体的用户操作（增删改查）？", "是否需要身份验证？"]
}

返回字段说明

字段	类型	说明
original_input	string	用户原始输入
analysis.core_intent	string	用户核心意图（一句话）
analysis.missing_elements	array	缺失的关键要素
analysis.ambiguous_parts	array	模糊不清的部分
analysis.assumptions	array	为补全做出的假设
clarified_intent.full_instruction	string	完整可执行指令
clarified_intent.action	string	核心动作
clarified_intent.target	string	操作对象
clarified_intent.constraints	array	约束条件
clarified_intent.expected_output	string	期望输出
confidence	string	置信度：high/medium/low
clarification_needed	array	仍需用户确认的问题

2️⃣ expand_instruction — 指令扩展

功能说明

将简短的指令扩展为 详细的、可执行的步骤，包含前置条件和交付物说明。

REST API 调用

POST /api/v1/expand
Content-Type: application/json
api-key: {your-api-key}

{
  "brief_input": "部署应用到生产环境",
  "task_type": "运维部署"
}

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "expand_instruction",
    "arguments": {
      "brief_input": "部署应用到生产环境",
      "task_type": "运维部署"
    }
  }
}

参数说明

参数	类型	必需	默认值	说明
brief_input	string	✅	-	简短的用户指令
task_type	string	❌	null	任务类型（如"代码编写"、"文档撰写"）

返回结果

{
  "success": true,
  "brief_input": "部署应用到生产环境",
  "expanded": {
    "goal": "将应用程序安全、稳定地部署到生产环境",
    "steps": [
      {
        "step": 1,
        "action": "代码审查与测试",
        "details": "确保所有代码通过 review，单元测试和集成测试全部通过",
        "expected_result": "测试报告显示 100% 通过"
      },
      {
        "step": 2,
        "action": "构建生产镜像",
        "details": "使用 CI/CD 流水线构建生产环境的 Docker 镜像",
        "expected_result": "生成带版本标签的 Docker 镜像"
      },
      {
        "step": 3,
        "action": "备份当前生产环境",
        "details": "备份数据库和配置文件，记录当前版本",
        "expected_result": "备份文件和回滚方案就绪"
      },
      {
        "step": 4,
        "action": "部署新版本",
        "details": "使用蓝绿部署或滚动更新策略发布新版本",
        "expected_result": "新版本容器运行正常"
      },
      {
        "step": 5,
        "action": "验证与监控",
        "details": "执行冒烟测试，检查日志和监控指标",
        "expected_result": "服务健康，无异常告警"
      }
    ],
    "prerequisites": ["代码已合并到 main 分支", "获得部署审批", "通知相关团队"],
    "deliverables": ["部署完成通知", "版本更新记录", "监控仪表盘链接"]
  },
  "full_instruction": "执行生产环境部署：首先确保代码审查和测试通过，然后构建生产镜像，备份当前环境后使用蓝绿部署策略发布新版本，最后执行验证并持续监控"
}

3️⃣ infer_parameters — 参数推断

功能说明

从用户的自然语言输入中 提取/推断参数值，用于填充工具或 API 调用的参数。

REST API 调用

POST /api/v1/infer-params
Content-Type: application/json
api-key: {your-api-key}

{
  "user_input": "查询上海最近一周的天气，要详细的",
  "available_params": ["city", "days", "detail_level", "format"],
  "param_descriptions": "{\"city\": \"城市名称\", \"days\": \"查询天数\", \"detail_level\": \"详细程度(simple/detailed)\", \"format\": \"输出格式(json/text)\"}"
}

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "infer_parameters",
    "arguments": {
      "user_input": "查询上海最近一周的天气，要详细的",
      "available_params": ["city", "days", "detail_level", "format"],
      "param_descriptions": "{\"city\": \"城市名称\", \"days\": \"查询天数\"}"
    }
  }
}

参数说明

参数	类型	必需	默认值	说明
user_input	string	✅	-	用户的自然语言输入
available_params	array<string>	✅	-	可用的参数名列表
param_descriptions	string	❌	null	参数描述（JSON 格式）

返回结果

{
  "success": true,
  "extracted_params": {
    "city": "上海",
    "days": "7"
  },
  "inferred_params": {
    "detail_level": {
      "value": "detailed",
      "reason": "用户明确要求'要详细的'"
    },
    "format": {
      "value": "json",
      "reason": "未指定格式，使用默认值 json"
    }
  },
  "missing_params": [],
  "final_params": {
    "city": "上海",
    "days": "7",
    "detail_level": "detailed",
    "format": "json"
  }
}

4️⃣ batch_clarify — 批量澄清

功能说明

一次性处理多条模糊输入，批量返回澄清结果。

REST API 调用

POST /api/v1/batch-clarify
Content-Type: application/json
api-key: {your-api-key}

{
  "inputs": [
    "帮我看看这个bug",
    "优化一下性能",
    "加个功能"
  ],
  "shared_context": "正在维护一个 Python Web 应用"
}

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "batch_clarify",
    "arguments": {
      "inputs": [
        "帮我看看这个bug",
        "优化一下性能",
        "加个功能"
      ],
      "shared_context": "正在维护一个 Python Web 应用"
    }
  }
}

参数说明

参数	类型	必需	默认值	说明
inputs	array<string>	✅	-	待澄清的输入列表
shared_context	string	❌	null	共享的上下文信息

返回结果

{
  "success": true,
  "results": [
    {
      "index": 1,
      "original": "帮我看看这个bug",
      "clarified": "请分析并定位当前 Python Web 应用中的 bug，提供错误原因分析和修复建议，需要提供具体的错误信息或日志",
      "key_assumptions": ["需要提供错误信息", "假设是运行时错误"]
    },
    {
      "index": 2,
      "original": "优化一下性能",
      "clarified": "请对 Python Web 应用进行性能优化，包括响应时间、内存使用和并发处理能力的改进，提供优化方案和预期效果",
      "key_assumptions": ["全面性能优化", "假设关注响应速度"]
    },
    {
      "index": 3,
      "original": "加个功能",
      "clarified": "请为 Python Web 应用添加新功能，需要提供功能需求描述、预期行为和接口设计",
      "key_assumptions": ["需要具体功能需求", "假设是业务功能"]
    }
  ],
  "total": 3
}

统一错误格式

成功：

{
  "success": true,
  "data": {}
}

失败：

{
  "success": false,
  "error": "错误描述"
}

服务端点

端点	方法	说明
/	GET	服务状态
/health	GET	健康检查
/mcp	POST	MCP JSON-RPC
/mcp/sse	GET/POST	MCP SSE 流式
/api/v1/clarify	POST	意图澄清
/api/v1/expand	POST	指令扩展
/api/v1/infer-params	POST	参数推断
/api/v1/batch-clarify	POST	批量澄清

部署信息

配置项	值
镜像地址	agnettaiji.azurecr.io/ai-agents/intent-clarify-agent:latest
服务端口	8000
健康检查	/health

典型使用场景

场景 1：作为前置处理器

在调用其他 Agent 之前，先用本 Agent 澄清用户意图：

用户输入 → Intent Clarify Agent → 澄清后的指令 → 业务 Agent

场景 2：参数提取

从用户自然语言中提取 API 调用参数：

"搜索北京到上海明天的机票" 
→ {from: "北京", to: "上海", date: "明天", type: "机票"}

场景 3：需求分析

将模糊的需求描述转化为具体的任务列表：

"做个登录功能" 
→ 详细的登录功能需求，包含表单字段、验证规则、安全要求等

11 KiB Raw Permalink Blame History Unescape Escape

意图澄清 Agent

功能概览

1⃣ clarify_intent — 意图澄清

功能说明

REST API 调用

MCP 调用

参数说明

返回结果

返回字段说明

2️⃣ expand_instruction — 指令扩展

功能说明

REST API 调用

MCP 调用

参数说明

返回结果

3️⃣ infer_parameters — 参数推断

功能说明

REST API 调用

MCP 调用

参数说明

返回结果

4️⃣ batch_clarify — 批量澄清

功能说明

REST API 调用

MCP 调用

参数说明

返回结果

统一错误格式

服务端点

部署信息

典型使用场景

场景 1：作为前置处理器

场景 2：参数提取

场景 3：需求分析

11 KiB

Raw Permalink Blame History