AI security detection, which is supported only in CN Southwest-Guiyang1 and CN North-Beijing4.

Function

AI security detection, which is used to perform security detection on LLM and tool calls.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

POST /v1/agent/block

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition Authentication token, which is used for API authentication. Constraints Mandatory. The value is transferred after the access token is obtained through the POST /v1/agent/auth/token API. The token can be reused within its validity period. After the validity period expires, you need to obtain a new token. Range A string in JWT format, consisting of three parts separated by periods (header.payload.signature). Default Value N/A

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
trace_id	No	String	Definition Link tracing ID, which is used for full-link tracing. Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A
session_id	Yes	String	Definition Session ID, which identifies a session. Constraints Mandatory Range The value can contain 1 to 256 characters. Default Value N/A
agent_id	Yes	String	Definition Unique ID of an agent, in UUID format. Constraints N/A Range The value is a string of 36 characters in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (a hexadecimal string of 8-4-4-4-12). Default Value N/A
user_id	No	String	Definition User identifiers Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A
user_name	No	String	Definition Username Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A
runtime_id	No	String	Definition Runtime ID Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A
request_id	Yes	String	Definition Unique request ID, in UUID format. It is used for request link tracing and deduplication. Constraints Mandatory Range The value is a string of 36 characters in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (a hexadecimal string of 8-4-4-4-12). Default Value N/A
timestamp	Yes	Long	Definition Request timestamp (Unix timestamp in milliseconds). Constraints Mandatory Range 0 ~ 9999999999999 Default Value N/A
type	Yes	String	Definition Interception point type. Constraints Mandatory Range before_llm_call: detection before LLM calling after_llm_call: detection after LLM calling before_tool_call: detection before tool calling after_tool_call: detection after tool calling Default Value N/A
streaming	No	Boolean	Definition Streaming or not Constraints N/A Range true: streaming false: non-streaming Default Value false
payload	Yes	Payload object	Definition Request payload. Use the corresponding field combination based on the type field. Constraints N/A Range N/A Default Value N/A

**Table 3** Payload
Parameter	Mandatory	Type	Description
prompt	No	String	Definition Prompt entered by the user. Constraints Optional. Whether to pass this parameter is determined by the type field. Range The value can contain 0 to 65,535 characters. Default Value N/A
messages	No	Array of Message objects	Definition Message list Constraints N/A Range 0 to 2048 message objects Default Value N/A

**Table 4** Message
Parameter	Mandatory	Type	Description
role	No	String	Definition Message role Constraints N/A Range user: user message assistant: AI assistant message system: system message developer: developer-level system command tool: tool response Default Value N/A
content	No	AnyType	Definition Message content. Two formats are supported. Constraints N/A Range String format: plain text content Array format: mixed content list, which can contain text and images Default Value N/A
tool_calls	No	Array of ToolCall objects	Definition Tool calling list (used when the assistant role calls a tool) Constraints N/A Range 0 to 100 ToolCall objects Default Value N/A
tool_call_id	No	String	Definition Unique ID of a tool call. Constraints N/A Range The value contains 1 to 2,048 characters. Default Value N/A

**Table 5** ToolCall
Parameter	Mandatory	Type	Description
id	Yes	String	Definition Unique ID of a tool call. Constraints Mandatory Range The value contains 1 to 2,048 characters. Default Value N/A
type	Yes	String	Definition Invocation mode. Constraints Mandatory Range The value can contain 1 to 64 characters. Default Value N/A
function	No	ToolCallFunction object	Information about the function invoked by the tool.

**Table 6** ToolCallFunction
Parameter	Mandatory	Type	Description
name	Yes	String	Definition Function name. Constraints Mandatory Range The value contains 1 to 2,048 characters. Default Value N/A
arguments	Yes	String	Definition Function parameters (JSON string) Constraints Mandatory Range The value contains 0 to 1,048,576 characters. Default Value N/A

Response Parameters

Status code: 200

**Table 7** Response body parameters
Parameter	Type	Description
action	String	Definition Action Range allow block ask: Ask the user for confirmation. alert: Generate an alert but do not block.
severity	String	Definition Severity. Range normal: No risk. low medium high critical
reason	String	Definition Reasons for decision-making Range The value contains 0 to 4096 characters.
message	String	Definition User-oriented detection information description Range The value contains 0 to 10240 characters.
evidence	Array of strings	Definition Evidence list (usually displayed when a block occurs) Range 0 to 100 evidence strings

Example Requests

AI security detection, which is used to perform security detection on LLM and tool calls.

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\"}"
        }
      } ]
    } ]
  }
}

Example Responses

Status code: 200

{
  "action" : "alert",
  "severity" : "low",
  "reason" : "PATH-NETRC",
  "message" : "Sorry, this operation matches a security policy. An alert has been triggered. You are attempting to access the netrc credential file, which stores FTP/HTTP login passwords in plaintext. To manage network credentials, use a more secure credential management tool.",
  "evidence" : [ "~/.netrc" ]
}

Status Codes

Status Code	Description
200	Request succeeded.

Error Codes

See Error Codes.

Parent Topic: AI Defender

Previous topic: AI Defender

Next topic: Obtaining an access token (for common authentication). Currently, only CN Southwest-Guiyang1 and CN North-Beijing4 support this function.