意图澄清 Agent (Intent Clarify Agent)

把模糊、不完整的人类输入补齐到可执行状态。

核心功能

只做一件事：将模糊、不完整、含糊的人类输入转化为清晰、完整、可执行的指令。

极适合放在任何 Agent 前面，让模型更准确理解用户要求。

提供能力

工具	功能
`clarify_intent`	澄清用户意图，补全缺失信息
`expand_instruction`	将简短指令扩展为详细步骤
`infer_parameters`	从自然语言推断参数值
`batch_clarify`	批量澄清多条输入

快速开始

本地运行

cd intent_clarify_agent
pip install -r requirements.txt
python run_api_server.py

Docker 运行

docker build -t intent-clarify-agent:latest .
docker run -p 8000:8000 -e OPENAI_API_KEY=your-key intent-clarify-agent:latest

使用示例

输入

"帮我写个脚本"

输出

{
  "original_input": "帮我写个脚本",
  "analysis": {
    "core_intent": "请求编写脚本",
    "missing_elements": ["脚本语言", "脚本功能", "运行环境"],
    "ambiguous_parts": ["'脚本'指什么类型的脚本"],
    "assumptions": ["假设是 Python 脚本", "假设用于自动化任务"]
  },
  "clarified_intent": {
    "full_instruction": "请使用 Python 编写一个自动化脚本，实现指定功能，输出为可直接运行的 .py 文件",
    "action": "编写",
    "target": "Python 脚本",
    "constraints": ["使用 Python 3.x", "代码需有注释"],
    "expected_output": "可运行的 Python 脚本文件"
  },
  "confidence": "low",
  "clarification_needed": ["具体需要脚本实现什么功能？", "有特定的编程语言偏好吗？"]
}

环境变量

变量	必需	说明
OPENAI_API_KEY	是	OpenAI 或 LiteLLM API Key
OPENAI_BASE_URL	否	API Base URL
MODEL_NAME	否	模型名称，默认 taiji/gpt-4o-mini
API_PORT	否	服务端口，默认 8000

项目结构

intent_clarify_agent/
├── Dockerfile
├── README.md
├── USAGE.md              # 详细使用文档
├── requirements.txt
├── run_api_server.py
└── src/
    ├── __init__.py
    └── server/
        ├── __init__.py
        ├── api_server.py   # FastAPI + MCP HTTP
        └── mcp_server.py   # MCP 工具定义

服务端点

端点	方法	说明
`/`	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