{
  "openapi": "3.1.0",
  "info": {
    "title": "保险顾问Agent API",
    "version": "4.0.0",
    "description": "AI保险产品搜索、推荐、对比与核保服务。覆盖65家保司483款在售产品。支持 MCP、A2A（任务级Agent协作）、OpenAI兼容 等多协议接入。",
    "contact": {
      "url": "https://whylingxi.cn/docs"
    }
  },
  "servers": [
    {
      "url": "https://whylingxi.cn",
      "description": "生产环境"
    }
  ],
  "paths": {
    "/chat": {
      "post": {
        "summary": "自然语言对话",
        "description": "多轮对话接口，适合人类用户或需要引导式交互的场景",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "message"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "用户消息"
                  },
                  "session_id": {
                    "type": "string",
                    "description": "会话ID，传入可保持多轮上下文"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "对话回复",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": {
                      "type": "string"
                    },
                    "reply": {
                      "type": "string",
                      "description": "Markdown格式回复"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "summary": "OpenAI兼容接口",
        "description": "兼容 OpenAI Chat Completions API 格式，可直接替换 OpenAI endpoint 使用",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "system",
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "model": {
                    "type": "string",
                    "description": "忽略，使用内置模型"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OpenAI格式回复"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP协议端点（Streamable HTTP）",
        "description": "Model Context Protocol 入口。使用 JSON-RPC 2.0 格式，支持 initialize → tools/list → tools/call 流程。详见 /docs",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {
                    "type": "integer"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "initialize",
                      "notifications/initialized",
                      "tools/list",
                      "tools/call"
                    ]
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 响应"
          }
        }
      }
    },
    "/a2a": {
      "post": {
        "summary": "A2A协议端点（Agent-to-Agent）",
        "description": "Google A2A 协议入口。支持 tasks/send、tasks/get、tasks/cancel。支持结构化 data parts 和自然语言 text parts 两种模式。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method",
                  "params"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {},
                  "method": {
                    "type": "string",
                    "enum": [
                      "tasks/send",
                      "tasks/get",
                      "tasks/cancel"
                    ]
                  },
                  "params": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "任务ID"
                      },
                      "message": {
                        "type": "object",
                        "description": "tasks/send时的消息体"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 响应，包含 task 对象"
          }
        }
      }
    },
    "/schema": {
      "get": {
        "summary": "能力Schema声明",
        "description": "返回各工具的字段优先级、默认值、返回结构。Agent应先调此接口了解参数要求。",
        "parameters": [
          {
            "name": "capability",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "recommend",
                "search",
                "compare",
                "premium",
                "underwriting"
              ]
            },
            "description": "指定查看某个能力，不传返回全部"
          }
        ],
        "responses": {
          "200": {
            "description": "Schema对象"
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "健康检查",
        "description": "返回服务状态和数据统计",
        "responses": {
          "200": {
            "description": "服务状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "total_products": {
                      "type": "integer"
                    },
                    "total_insurers": {
                      "type": "integer"
                    },
                    "total_categories": {
                      "type": "integer"
                    },
                    "tools": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/docs": {
      "get": {
        "summary": "开发者文档",
        "description": "完整的接入指南（HTML页面）",
        "responses": {
          "200": {
            "description": "HTML文档页"
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "summary": "Agent Card（A2A发现）",
        "description": "符合A2A规范的Agent Card，包含能力、技能、协议信息",
        "responses": {
          "200": {
            "description": "Agent Card JSON"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "insurer": {
            "type": "string"
          },
          "premium": {
            "type": "number",
            "description": "保费（元/年）"
          },
          "price_type": {
            "type": "string",
            "enum": [
              "exact",
              "starting_from",
              "estimated"
            ]
          },
          "source_url": {
            "type": "string",
            "format": "uri"
          },
          "highlights": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Recommendation": {
        "type": "object",
        "properties": {
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "input_echo": {
            "type": "object",
            "description": "回显接收到的参数"
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "recommendations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "products": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Product"
                  }
                }
              }
            }
          },
          "total_premium_estimate": {
            "type": "number",
            "nullable": true
          },
          "missing_fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "priority": {
                  "type": "string"
                },
                "improvement": {
                  "type": "string"
                }
              }
            }
          },
          "next_questions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "question": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}