# AI安全检测 - DetectAgentRisk #### 功能介绍 AI安全检测，用于对LLM调用和工具调用进行安全检测 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-hss2.0/hss_02_0007.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-hss2.0/hss_02_0022.html)。 - 如果使用身份策略授权，当前API调用无需身份策略权限。 #### URI POST /v1/agent/block #### 请求参数 表1请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**: 认证 Token，用于接口鉴权 **约束限制**: 必填。通过 POST /v1/agent/auth/token 接口获取 access_token 后传入。Token 有效期内可重复使用，过期后需重新获取 **取值范围**: JWT 格式的字符串，由 header.payload.signature 三部分组成，以点号分隔 **默认取值**: 不涉及 | 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | trace_id | 否 | String | **参数解释**: 链路追踪 ID，用于全链路跟踪 **约束限制**: 不涉及 **取值范围**: 字符长度1-128位 **默认取值**: 不涉及 | | session_id | 是 | String | **参数解释**: 会话 ID，标识一次对话会话 **约束限制**: 必填 **取值范围**: 字符长度1-256位 **默认取值**: 不涉及 | | agent_id | 是 | String | **参数解释**: Agent 唯一标识，UUID 格式 **约束限制**: 不涉及 **取值范围**: 字符长度36位，格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx（8-4-4-4-12 的十六进制字符串） **默认取值**: 不涉及 | | user_id | 否 | String | **参数解释**: 用户标识 **约束限制**: 不涉及 **取值范围**: 字符长度1-128位 **默认取值**: 不涉及 | | user_name | 否 | String | **参数解释**: 用户名称 **约束限制**: 不涉及 **取值范围**: 字符长度1-128位 **默认取值**: 不涉及 | | runtime_id | 否 | String | **参数解释**: 运行时 ID **约束限制**: 不涉及 **取值范围**: 字符长度1-128位 **默认取值**: 不涉及 | | request_id | 是 | String | **参数解释**: 请求唯一标识 ID，UUID 格式，用于请求链路追踪和去重 **约束限制**: 必填 **取值范围**: 字符长度36位，格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx（8-4-4-4-12 的十六进制字符串） **默认取值**: 不涉及 | | timestamp | 是 | Long | **参数解释**: 请求时间戳（毫秒级 Unix 时间戳） **约束限制**: 必填 **取值范围**: 0 \~ 9999999999999 **默认取值**: 不涉及 | | type | 是 | String | **参数解释**: 拦截点类型 **约束限制**: 必填 **取值范围**: - before_llm_call: LLM 调用前检测 - after_llm_call: LLM 调用后检测 - before_tool_call: 工具调用前检测 - after_tool_call: 工具调用后检测 **默认取值**: 不涉及 | | streaming | 否 | Boolean | **参数解释**: 是否流式 **约束限制**: 不涉及 **取值范围**: - true: 流式 - false: 非流式 **默认取值**: false | | payload | 是 | [Payload] object | **参数解释**: 请求载荷，根据 type 字段使用对应的字段组合 **约束限制**: 不涉及 **取值范围**: 不涉及 **默认取值**: 不涉及 | 表3Payload | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | prompt | 否 | String | **参数解释**: 用户输入的提示词 **约束限制**: 可选参数，根据 type 字段区分是否传入 **取值范围**: 字符长度0-65535位 **默认取值**: 不涉及 | | messages | 否 | Array of [Message] objects | **参数解释**: 消息列表 **约束限制**: 不涉及 **取值范围**: 0-2048个 Message 对象 **默认取值**: 不涉及 | 表4Message | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | role | 否 | String | **参数解释**: 消息角色 **约束限制**: 必填 **取值范围**: - user: 用户消息 - assistant: AI 助手消息 - system: 系统提示消息 - developer: 开发者级别的系统指令 - tool: 工具返回信息 **默认取值**: 不涉及 | | content | 否 | AnyType | **参数解释**: 消息内容，支持两种格式 **约束限制**: 不涉及 **取值范围**: - 字符串格式：纯文本内容 - 数组格式：混合内容列表，可包含文本和图片 **默认取值**: 不涉及 | | tool_calls | 否 | Array of [ToolCall] objects | **参数解释**: 工具调用列表（assistant 角色调用工具时使用） **约束限制**: 不涉及 **取值范围**: 0-100个 ToolCall 对象 **默认取值**: 不涉及 | | tool_call_id | 否 | String | **参数解释**: 工具调用唯一 ID **约束限制**: 不涉及 **取值范围**: 字符长度1-2048位 **默认取值**: 不涉及 | 表5ToolCall | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | id | 是 | String | **参数解释**: 工具调用唯一 ID **约束限制**: 必填 **取值范围**: 字符长度1-2048位 **默认取值**: 不涉及 | | type | 是 | String | **参数解释**: 调用类型 **约束限制**: 必填 **取值范围**: 字符长度1-64位 **默认取值**: 不涉及 | | function | 否 | [ToolCallFunction] object | 工具调用的函数信息 | 表6ToolCallFunction | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释**: 函数名称 **约束限制**: 必填 **取值范围**: 字符长度1-2048位 **默认取值**: 不涉及 | | arguments | 是 | String | **参数解释**: 函数参数（JSON 字符串格式） **约束限制**: 必填 **取值范围**: 字符长度0-1048576位 **默认取值**: 不涉及 | #### 响应参数 **状态码：200** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | action | String | **参数解释**: 执行动作 **取值范围**: - allow: 允许放行 - block: 拦截阻止 - ask: 询问用户确认 - alert: 仅告警不拦截 | | severity | String | **参数解释**: 严重程度 **取值范围**: - normal: 无风险 - low: 低风险 - medium: 中风险 - high: 高风险 - critical: 严重风险 | | reason | String | **参数解释**: 决策原因描述 **取值范围**: 字符长度0-4096位 | | message | String | **参数解释**: 面向用户的检测信息描述 **取值范围**: 字符长度0-10240位 | | evidence | Array of strings | **参数解释**: 证据列表（通常在 block 时出现） **取值范围**: 0-100个证据字符串 | #### 请求示例 AI安全检测，用于对LLM调用和工具调用进行安全检测 ``` PUT https://{endpoint}/v1/agent/block { "trace_id" : "tc016", "session_id" : "s016", "agent_id" : "8865f589-b1af-33a1-a5e0-d09deb4a74f6", "user_id" : "6e5b687e10224a18af014e5d81bf9b3c", "runtime_id" : "76b7dc1b84504e8e894a7623c57569d4", "request_id" : "9faaffb4-8e8e-4da9-80a2-d19bb0246a2b", "timestamp" : 1780312740939, "type" : "before_tool_call", "streaming" : false, "payload" : { "messages" : [ { "role" : "assistant", "tool_calls" : [ { "id" : "11", "type" : "function", "function" : { "name" : "bash", "arguments" : "{\"path\": \"~/.netrc\"}" } } ] } ] } } ``` #### 响应示例 **状态码：200** 请求已成功 ``` { "action" : "alert", "severity" : "low", "reason" : "PATH-NETRC", "message" : "抱歉，该操作已命中安全策略，对应动作(alert)。检测到您尝试访问netrc凭证文件，该文件以明文存储FTP/HTTP登录密码。如需管理网络凭证，请使用更安全的凭证管理工具。", "evidence" : [ "~/.netrc" ] } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 请求已成功 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-hss2.0/ErrorCode.html)。