# 行动召回

## 1、行动查询接口请求示例

请求示例
```json
curl --location 'http://192.168.232.11:13018/api/ontology-query/in/v1/knowledge-networks/kn_medical/action-types/generate_treatment_plan' \
--header 'x-account-id: bdb78b62-6c48-11f0-af96-fa8dcc0a06b2' \
--header 'x-http-method-override: GET' \
--header 'x-account-type: user' \
--header 'Content-Type: application/json' \
--data '{
    "unique_identities": [
        {
            "disease_id": "disease_000001"
        },
        {
            "disease_id": "disease_002696"
        }
    ]
}'
```

响应结果示例
```json
{
    "action_source": {
        "type": "tool",
        "box_id": "e59f35f8-65f3-46bb-b5f1-a428380b3edc",
        "tool_id": "7acb8add-ecd0-45cf-bd4d-57674c3c69b0"
    },
    "actions": [
        {
            "parameters": {
                "x-account-id": "test",
                "x-account-type": "user"
            },
            "dynamic_params": {
                "include_type_info": null,
                "include_logic_params": null,
                "condition": {
                    "sub_conditions": null,
                    "value": null,
                    "value_from": null,
                    "field": null,
                    "operation": null
                },
                "need_total": null,
                "sort": null,
                "X-HTTP-Method-Override": null,
                "limit": null,
                "properties": null,
                "kn_id": null,
                "ot_id": null
            }
        },
        {
            "parameters": {
                "x-account-id": "test",
                "x-account-type": "user"
            },
            "dynamic_params": {
                "ot_id": null,
                "include_logic_params": null,
                "X-HTTP-Method-Override": null,
                "condition": {
                    "field": null,
                    "operation": null,
                    "sub_conditions": null,
                    "value": null,
                    "value_from": null
                },
                "need_total": null,
                "properties": null,
                "kn_id": null,
                "include_type_info": null,
                "limit": null,
                "sort": null
            }
        }
    ],
    "total_count": 2,
    "overall_ms": 129
}
```

## 2、获取工具详情接口示例
基于第一步中的
"action_source": {
        "type": "tool",
        "box_id": "e59f35f8-65f3-46bb-b5f1-a428380b3edc",
        "tool_id": "7acb8add-ecd0-45cf-bd4d-57674c3c69b0"
}
如果type= tool, 则根据 box_id和tool_id获取工具详情信息。

请求示例
```json
curl --location 'http://agent-operator-integration:9000/api/agent-operator-integration/internal-v1/tool-box/389811bd-c5f9-4913-9eb1-2122510a615b/tool/4e2bfd63-7a4b-400c-bd25-a5bd4dddb238' \
--header 'x-account-id: bdb78b62-6c48-11f0-af96-fa8dcc0a06b2' \
--header 'x-account-type: user'
```

响应示例
```json
{
    "tool_id": "4e2bfd63-7a4b-400c-bd25-a5bd4dddb238",
    "name": "根据单个对象类查询对象实例",
    "description": "该接口基于业务知识网络语义检索接口返回的对象类定义，查询具体的对象实例数据。",
    "status": "enabled",
    "metadata_type": "openapi",
    "metadata": {
        "version": "2eb666a8-6ea5-4c35-bbc9-c0cd421804c6",
        "summary": "search_object_instance",
        "description": "该接口基于业务知识网络语义检索接口返回的对象类定义，查询具体的对象实例数据。",
        "server_url": "http://ontology-query-svc:13018",
        "path": "/api/ontology-query/in/v1/knowledge-networks/{kn_id}/object-types/{ot_id}",
        "method": "POST",
        "create_time": 1766023172474165526,
        "update_time": 1766025241343437798,
        "create_user": "bdb78b62-6c48-11f0-af96-fa8dcc0a06b2",
        "update_user": "bdb78b62-6c48-11f0-af96-fa8dcc0a06b2",
        "api_spec": {
            "parameters": [
                {
                    "name": "x-account-id",
                    "in": "header",
                    "description": "账户ID",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "x-account-type",
                    "in": "header",
                    "description": "账户类型",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "kn_id",
                    "in": "path",
                    "description": "业务知识网络ID",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "ot_id",
                    "in": "path",
                    "description": "对象类ID",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "include_type_info",
                    "in": "query",
                    "description": "是否包含对象类信息, 默认false，不包含",
                    "required": false,
                    "schema": {
                        "type": "boolean"
                    }
                },
                {
                    "name": "include_logic_params",
                    "in": "query",
                    "description": "包含逻辑属性的计算参数，默认false，返回结果不包含逻辑属性的字段和值",
                    "required": false,
                    "schema": {
                        "type": "boolean"
                    }
                },
                {
                    "name": "X-HTTP-Method-Override",
                    "in": "header",
                    "description": "重载 post，实际上是 get 方法",
                    "required": true,
                    "schema": {
                        "enum": [
                            "GET"
                        ],
                        "type": "string"
                    }
                }
            ],
            "request_body": {
                "description": "",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/FirstQueryWithSearchAfter"
                        }
                    }
                },
                "required": false
            },
            "responses": [
                {
                    "status_code": "200",
                    "description": "ok",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ObjectDataResponse"
                            }
                        }
                    }
                }
            ],
            "components": {
                "schemas": {
                    "DataProperty": {
                        "description": "数据属性",
                        "required": [
                            "name",
                            "display_name",
                            "type",
                            "comment",
                            "mapped_field",
                            "index",
                            "fulltext_config",
                            "vector_config"
                        ],
                        "properties": {
                            "display_name": {
                                "description": "属性显示名",
                                "type": "string"
                            },
                            "fulltext_config": {
                                "$ref": "#/components/schemas/FulltextConfig"
                            },
                            "index": {
                                "type": "boolean",
                                "description": "是否开启索引，默认是true"
                            },
                            "mapped_field": {
                                "$ref": "#/components/schemas/ViewField"
                            },
                            "name": {
                                "description": "属性名称。只能包含小写英文字母、数字、下划线（_）、连字符（-），且不能以下划线和连字符开头",
                                "type": "string"
                            },
                            "type": {
                                "type": "string",
                                "description": "属性数据类型。除了视图的字段类型之外，还有 metric、objective、event、trace、log、operator"
                            },
                            "vector_config": {
                                "$ref": "#/components/schemas/VectorConfig"
                            },
                            "comment": {
                                "type": "string",
                                "description": "属性描述"
                            }
                        },
                        "type": "object"
                    },
                    "VectorConfig": {
                        "description": "向量索引的配置",
                        "required": [
                            "dimension"
                        ],
                        "properties": {
                            "dimension": {
                                "type": "integer",
                                "description": "向量维度"
                            }
                        },
                        "type": "object"
                    },
                    "ViewField": {
                        "type": "object",
                        "description": "视图字段信息",
                        "required": [
                            "name"
                        ],
                        "properties": {
                            "type": {
                                "type": "string",
                                "description": "视图字段类型，查看时有此字段"
                            },
                            "display_name": {
                                "type": "string",
                                "description": "字段显示名.查看时有此字段"
                            },
                            "name": {
                                "description": "字段名称",
                                "type": "string"
                            }
                        }
                    },
                    "Parameter4Metric": {
                        "type": "object",
                        "description": "逻辑参数",
                        "required": [
                            "name",
                            "value_from",
                            "operation"
                        ],
                        "properties": {
                            "value_from": {
                                "enum": [
                                    "property",
                                    "input"
                                ],
                                "type": "string",
                                "description": "值来源"
                            },
                            "name": {
                                "type": "string",
                                "description": "参数名称"
                            },
                            "operation": {
                                "description": "操作符。映射指标模型的属性时，此字段必须",
                                "enum": [
                                    "in",
                                    "=",
                                    "!=",
                                    ">",
                                    ">=",
                                    "<",
                                    "<="
                                ],
                                "type": "string"
                            },
                            "value": {
                                "type": "string",
                                "description": "参数值。value_from=property时，填入的是对象类的数据属性名称；value_from=input时，不设置此字段"
                            }
                        }
                    },
                    "FulltextConfig": {
                        "type": "object",
                        "description": "全文索引的配置",
                        "required": [
                            "analyzer",
                            "field_keyword"
                        ],
                        "properties": {
                            "field_keyword": {
                                "type": "boolean",
                                "description": "是否保留原始字符串，保留原始字符串可用于精确匹配。默认是false"
                            },
                            "analyzer": {
                                "type": "string",
                                "description": "分词器",
                                "enum": [
                                    "standard",
                                    "ik_max_word"
                                ]
                            }
                        }
                    },
                    "ObjectTypeDetail": {
                        "properties": {
                            "icon": {
                                "type": "string",
                                "description": "图标"
                            },
                            "primary_keys": {
                                "type": "array",
                                "description": "主键",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "comment": {
                                "type": "string",
                                "description": "备注（可以为空）"
                            },
                            "display_key": {
                                "description": "对象实例的显示属性",
                                "type": "string"
                            },
                            "color": {
                                "type": "string",
                                "description": "颜色"
                            },
                            "id": {
                                "type": "string",
                                "description": "对象类ID"
                            },
                            "data_source": {
                                "$ref": "#/components/schemas/DataSource"
                            },
                            "kn_id": {
                                "type": "string",
                                "description": "业务知识网络id"
                            },
                            "name": {
                                "type": "string",
                                "description": "对象类名称"
                            },
                            "concept_groups": {
                                "type": "array",
                                "description": "概念分组id",
                                "items": {
                                    "$ref": "#/components/schemas/ConceptGroup"
                                }
                            },
                            "updater": {
                                "type": "string",
                                "description": "最近一次修改人"
                            },
                            "create_time": {
                                "type": "integer",
                                "format": "int64",
                                "description": "创建时间"
                            },
                            "detail": {
                                "type": "string",
                                "description": "说明书。按需返回，若指定了include_detail=true，则返回，否则不返回。列表查询时不返回此字段"
                            },
                            "update_time": {
                                "type": "integer",
                                "format": "int64",
                                "description": "最近一次更新时间"
                            },
                            "branch": {
                                "type": "string",
                                "description": "分支ID"
                            },
                            "tags": {
                                "type": "array",
                                "description": "标签。 （可以为空）",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "data_properties": {
                                "type": "array",
                                "description": "数据属性",
                                "items": {
                                    "$ref": "#/components/schemas/DataProperty"
                                }
                            },
                            "module_type": {
                                "description": "模块类型",
                                "enum": [
                                    "object_type"
                                ],
                                "type": "string"
                            },
                            "creator": {
                                "type": "string",
                                "description": "创建人ID"
                            },
                            "logic_properties": {
                                "type": "array",
                                "description": "逻辑属性",
                                "items": {
                                    "$ref": "#/components/schemas/LogicProperty"
                                }
                            }
                        },
                        "type": "object",
                        "description": "对象类信息"
                    },
                    "LogicProperty": {
                        "type": "object",
                        "description": "逻辑属性",
                        "required": [
                            "name",
                            "data_source",
                            "parameters"
                        ],
                        "properties": {
                            "parameters": {
                                "type": "array",
                                "description": "逻辑所需的参数",
                                "items": {
                                    "$ref": "#/components/schemas/Parameter"
                                }
                            },
                            "type": {
                                "type": "string",
                                "description": "属性数据类型。除了视图的字段类型之外，还有 metric、objective、event、trace、log、operator"
                            },
                            "comment": {
                                "description": "属性描述",
                                "type": "string"
                            },
                            "data_source": {
                                "$ref": "#/components/schemas/LogicSource"
                            },
                            "display_name": {
                                "type": "string",
                                "description": "属性显示名"
                            },
                            "index": {
                                "type": "boolean",
                                "description": "是否开启索引，默认是true"
                            },
                            "name": {
                                "description": "属性名称。只能包含小写英文字母、数字、下划线（_）、连字符（-），且不能以下划线和连字符开头",
                                "type": "string"
                            }
                        }
                    },
                    "Parameter": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/Parameter4Operator"
                            },
                            {
                                "$ref": "#/components/schemas/Parameter4Metric"
                            }
                        ],
                        "type": "object",
                        "description": "逻辑/指标参数"
                    },
                    "ConceptGroup": {
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "概念分组名称"
                            },
                            "id": {
                                "type": "string",
                                "description": "概念分组ID"
                            }
                        },
                        "type": "object",
                        "description": "概念分组",
                        "required": [
                            "id",
                            "name"
                        ]
                    },
                    "DataSource": {
                        "type": "object",
                        "description": "数据来源",
                        "required": [
                            "type",
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "数据视图ID"
                            },
                            "name": {
                                "description": "名称。查看详情时返回。",
                                "type": "string"
                            },
                            "type": {
                                "type": "string",
                                "description": "数据来源类型为数据视图",
                                "enum": [
                                    "data_view"
                                ]
                            }
                        }
                    },
                    "FirstQueryWithSearchAfter": {
                        "description": "分页查询的第一次查询请求",
                        "required": [
                            "sort",
                            "limit"
                        ],
                        "properties": {
                            "condition": {
                                "$ref": "#/components/schemas/Condition"
                            },
                            "limit": {
                                "type": "integer",
                                "description": "返回的数量，默认值 10。范围 1-10000"
                            },
                            "need_total": {
                                "type": "boolean",
                                "description": "是否需要总数，默认false"
                            },
                            "properties": {
                                "description": "指定返回的对象属性字段列表，默认返回所有属性。",
                                "items": {
                                    "type": "string"
                                },
                                "type": "array"
                            },
                            "sort": {
                                "type": "array",
                                "description": "排序字段",
                                "items": {
                                    "$ref": "#/components/schemas/Sort"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "LogicSource": {
                        "type": "object",
                        "description": "数据来源",
                        "required": [
                            "type",
                            "id"
                        ],
                        "properties": {
                            "type": {
                                "description": "数据来源类型",
                                "enum": [
                                    "metric",
                                    "operator"
                                ],
                                "type": "string"
                            },
                            "id": {
                                "description": "数据来源ID",
                                "type": "string"
                            },
                            "name": {
                                "type": "string",
                                "description": "名称。查看详情时返回。"
                            }
                        }
                    },
                    "ObjectDataResponse": {
                        "required": [
                            "groups",
                            "type",
                            "datas",
                            "search_after"
                        ],
                        "properties": {
                            "search_after": {
                                "type": "array",
                                "description": "表示返回的最后一个文档的排序值，获取这个用于下一次 search_after 分页",
                                "items": {}
                            },
                            "total_count": {
                                "type": "integer",
                                "description": "总条数"
                            },
                            "datas": {
                                "items": {
                                    "type": "object"
                                },
                                "type": "array",
                                "description": "对象实例数据。动态数据字段，其值可以是基本类型、MetricProperty或OperatorProperty"
                            },
                            "object_type": {
                                "$ref": "#/components/schemas/ObjectTypeDetail"
                            }
                        },
                        "type": "object",
                        "description": "节点（对象类）信息"
                    },
                    "Sort": {
                        "description": "排序字段",
                        "required": [
                            "field",
                            "direction"
                        ],
                        "properties": {
                            "direction": {
                                "enum": [
                                    "desc",
                                    "asc"
                                ],
                                "type": "string",
                                "description": "排序方向"
                            },
                            "field": {
                                "type": "string",
                                "description": "排序字段"
                            }
                        },
                        "type": "object"
                    },
                    "Parameter4Operator": {
                        "description": "逻辑参数",
                        "required": [
                            "name",
                            "value_from"
                        ],
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "参数名称"
                            },
                            "source": {
                                "type": "string",
                                "description": "参数来源"
                            },
                            "type": {
                                "type": "string",
                                "description": "参数类型"
                            },
                            "value": {
                                "type": "string",
                                "description": "参数值。value_from=property时，填入的是对象类的数据属性名称；value_from=input时，不设置此字段"
                            },
                            "value_from": {
                                "enum": [
                                    "property",
                                    "input"
                                ],
                                "type": "string",
                                "description": "值来源"
                            }
                        },
                        "type": "object"
                    },
                    "Condition": {
                        "description": "过滤条件结构，用于构建对象实例的查询筛选条件。\n\n**重要规则：**\n- `value_from` 和 `value` 必须同时使用，不能单独使用\n- `value_from` 当前仅支持 \"const\"（常量值）\n- 当使用 `value_from: \"const\"` 时，必须同时提供 `value` 字段\n",
                        "required": [
                            "operation"
                        ],
                        "properties": {
                            "sub_conditions": {
                                "type": "array",
                                "description": "子过滤条件数组，用于逻辑操作符(and/or)的组合查询",
                                "items": {
                                    "$ref": "#/components/schemas/Condition"
                                }
                            },
                            "value": {
                                "description": "字段值，格式根据操作符类型而定：\n- 比较操作符: 单个值\n- 范围查询: [min, max]数组\n- 集合操作: 值数组\n- 向量搜索: 特定格式数组\n\n**必须与 `value_from: \"const\"` 同时使用**\n"
                            },
                            "value_from": {
                                "type": "string",
                                "description": "字段值来源。\n\n**重要：** 当前仅支持 \"const\"（常量值），且必须与 `value` 字段同时使用\n",
                                "enum": [
                                    "const"
                                ]
                            },
                            "field": {
                                "type": "string",
                                "description": "字段名称，也即对象类的属性名称"
                            },
                            "operation": {
                                "enum": [
                                    "and",
                                    "or",
                                    "==",
                                    "!=",
                                    ">",
                                    ">=",
                                    "<",
                                    "<=",
                                    "in",
                                    "not_in",
                                    "like",
                                    "not_like",
                                    "exist",
                                    "not_exist",
                                    "match"
                                ],
                                "type": "string",
                                "description": "查询条件操作符。\n**注意：** 虽然这里列出了所有可能的操作符，但每个对象类实际支持的操作符列表以对象类定义中的 `condition_operations` 字段为准。\n"
                            }
                        },
                        "type": "object"
                    }
                }
            },
            "callbacks": null,
            "security": null,
            "tags": null,
            "external_docs": null
        }
    },
    "use_rule": "text类型的字段不参与排序",
    "global_parameters": {
        "name": "",
        "description": "",
        "required": false,
        "in": "",
        "type": "",
        "value": null
    },
    "create_time": 1766023172475301375,
    "update_time": 1766394678316323090,
    "create_user": "bdb78b62-6c48-11f0-af96-fa8dcc0a06b2",
    "update_user": "bdb78b62-6c48-11f0-af96-fa8dcc0a06b2",
    "extend_info": {}
}
```


## 3、行动召回接口逻辑设计

1、定义行动召回接口，对行动查询接口进行封装。

行动查询接口要求传递 unique_identities 是一个 json array。 我们封装的行动召回接口只接收 json object。

请求示例：
```json
{
    "unique_identity": {
            "disease_id": "disease_000001"
    }
}
```

2、返回格式进行封装

```json
{
    "_dynamic_tools": [
        {
            "name": "tool_name",
            "description": "工具描述",
            "parameters": { // openai function call 风格要求的input schema
                "type": "object",
                "properties": {...}
                "required": [...]
            },
            "api_url": "",
            "original_schema": { // 对应工具详情中的api_spec

            },
            "fixed_params": { // 固定参数

            }
            ""
        }
    ]
}
```

需求逻辑如下：
1、本质上是对行动查询接口进行封装。返回定义的格式
2、行动召回接口只接收unique_identity。 行动查询接口接收unique_identities
3、需要基于行动查询的响应结果的基础上进行处理
    a. 如果type=tool, 则根据box_id和tool_id 调用获取工具详情信息。 预留type=mcp类型的实现。
    b. 只解析 "actions": []的第一个元素数据。 parameters映射到 fixed_params
    c. api_url模板： http://agent-operator-integration:9000/api/agent-operator-integration/internal-v1/tool-box/{box_id}/proxy/{tool_id}
    d. 行动召回结果中parameters 需要根据 original_schema进行转换。请单独定义一个口子，后续我们再深入讨论实现逻辑，先设置为todo


