# 执行数据面请求调用 - ExecuteCode #### 功能介绍 该API用于在沙箱中执行各类操作请求，比如执行代码、执行命令、写入文件、读取文件、列出文件、删除文档等操作。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 当前API调用无需身份策略权限。 #### URI POST /v1/code-interpreters/{code_interpreter_name}/invoke 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | code_interpreter_name | 是 | String | **参数解释：** 与会话关联的代码解释器的唯一标识符。 代码解释器名称获取方式： 1.进入AgentArts平台，在左侧导航栏选择"组件库 \> 沙箱工具 "。 2.在代码解释器列表中"代码解释器名称/ID"处获取代码解释器名称。 **约束限制：** 必须为已创建的代码解释器名称，若不存在则返回404错误。 **取值范围：** 符合正则\^\[a-z\]\[a-z0-9-\]{0,46}\[a-z0-9\]$，即必须以小写字母开头，小写字母或数字结尾，中间可包含数字、小写字母、中划线，字符长度必须在2-40个字符之间。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-HW-AgentArts-Code-Interpreter-Session-Id | 是 | String | **参数解释：** 使用的代码解释器会话的唯一标识符。 **约束限制：** 必须为StartCodeInterpreterSession接口返回的活动会话ID。session_id不可为空，格式不合法返回400错误，会话不存在或已过期返回404错误。 **取值范围：** 由StartCodeInterpreterSession接口返回的session_id，长度1-128字符。 **默认取值：** 不涉及。 | | Authorization | 是 | String | **参数解释**： 本次智能体工具调用对应的身份认证凭据。需要根据实际的智能体工具的入站身份认证方式获取对应的身份认证凭据。 API Key认证、IAM认证及OAuth 2.0认证具体请参见[认证鉴权](https://support.huaweicloud.com/api-agentarts/agentarts_07_0005.html)。 **约束限制**: 不涉及。 **取值范围**： 不超过4096位字符。 **默认取值**: 不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | operate_type | 是 | String | **参数解释：** 此次请求操作类型。 **约束限制：** 必须为指定的枚举值之一，传入非法值将返回400错误。operate_type决定了arguments中哪些字段必选： - execute_code：code必选，language必选 - execute_command：command必选 - read_files：paths必选 - list_files：directory_path可选 - remove_files：paths必选 - write_files：write_contents必选 - execute_code：执行代码 - execute_command：执行命令 - read_files：读取文件 - list_files：列举文件 - remove_files：删除文件 - write_files：写入文件 **取值范围：** **默认取值：** 不涉及。 | | arguments | 是 | [CodeInterpreterToolArguments] object | **参数解释：** 此次请求操作参数。 **约束限制：** arguments不可为空对象，其中必选字段由operate_type决定，具体见各子字段说明及operate_type描述。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表4CodeInterpreterToolArguments | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | clear_context | 否 | Boolean | **参数解释：** 是否需要清除工具的上下文。 **约束限制：** 不涉及。 **取值范围：** - true 清除 - false 不清除 **默认取值：** false | | code | 否 | String | **参数解释：** 要在代码解释器会话中执行的代码。这是指定编程语言的源代码，将由代码解释器执行。 **约束限制：** 长度限制：最小长度为 0，最大长度为 1048576。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | command | 否 | String | **参数解释：** 要使用该工具执行的命令。 **约束限制：** 长度限制：最小长度为 0，最大长度为 65536。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | language | 否 | String | **参数解释：** 要执行的代码所使用的编程语言。即告诉代码解释器使用哪种语言运行时来执行代码。 **约束限制：** 不涉及。 **取值范围：** 支持语言： - python **默认取值：** 不涉及。 | | write_contents | 否 | Array of [CodeInterpreterToolContent] objects | **参数解释：** 当请求操作为 write_files 时，待写入的内容，包含待写入数据内容和文件路径。 **约束限制：** 列表限制：最小元素数量为0，最大元素数量为1000。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | directory_path | 否 | String | **参数解释：** 当请求操作为 list_files时，所需 list 的目录。 **约束限制：** 长度限制：最小长度为 0，最大长度为 4096。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | paths | 否 | Array of strings | **参数解释：** 当请求操作为 read_files / remove_files时， 所需读取或者删除的文件路径。 **约束限制：** 需保证每个路径唯一，列表限制：最小元素数量为0，最大元素数量为1000。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5CodeInterpreterToolContent | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | path | 是 | String | **参数解释：** 写入数据时的目标地址。 **约束限制：** 长度限制：最小长度0字符，最大长度4096字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | blob | 否 | File | **参数解释：** 二进制内容。 **约束限制：** 采用Base64编码，解码后最大长度104857600字节（约100MB）。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | text | 否 | String | **参数解释：** 文本内容。 **约束限制：** 长度限制：最小长度0字符，最大长度104857600字符（约100MB）。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | result | [CodeInterpreterResult] object | **参数解释：** 代码解释器会话中执行代码后产生的输出。 **取值范围：** 不涉及。 | 表7CodeInterpreterResult | 参数 | 参数类型 | 描述 | |:---|:---|:---| | content | Array of [CodeInterpreterContentBlock] objects | **参数解释：** 执行结果的文本内容。这包括代码执行的标准输出，例如打印语句、控制台输出和结果的文本表示。 **取值范围：** 不涉及。 | | is_error | Boolean | **参数解释：** 指示结果是否代表错误。如果为真，则内容包含错误消息或异常信息。如果为假，则内容包含成功执行的结果。 **取值范围：** 不涉及。 | | structured_content | [CodeInterpreterResultStructuredContent] object | **参数解释：** 执行结果的结构化内容。这包括有关执行的附加元数据，例如执行时间、内存使用情况以及输出数据的结构化表示。格式取决于具体的代码解释器和执行上下文。 **取值范围：** 不涉及。 | 表8CodeInterpreterContentBlock | 参数 | 参数类型 | 描述 | |:---|:---|:---| | type | String | **参数解释：** 该数据块的内容类型。 **取值范围：** - text：文本内容。 - image：图片内容。 - resource：资源内容。 - resource_link：资源链接。 | | data | String | **参数解释：** 该数据块的二进制数据内容。 **取值范围：** 不涉及。 | | description | String | **参数解释：** 内容块的描述。 **取值范围：** 不涉及。 | | mime_type | String | **参数解释：** 资源内容的 MIME 类型。 **取值范围：** 不涉及。 | | name | String | **参数解释：** 内容块的名称。 **取值范围：** 不涉及。 | | size | Integer | **参数解释：** 内容大小（以字节为单位）。 **取值范围：** 不涉及。 | | text | String | **参数解释：** 该代码块的文本内容。 **取值范围：** 不涉及。 | | uri | String | **参数解释：** 内容的URI。 **取值范围：** 不涉及。 | | resource | [ResourceContent] object | **参数解释：** 与内容块关联的资源。 **取值范围：** 不涉及。 | 表9ResourceContent | 参数 | 参数类型 | 描述 | |:---|:---|:---| | type | String | **参数解释：** 资源内容的类型。 **取值范围：** - text：文本资源。 - blob：二进制资源。 | | blob | String | **参数解释：** Base64编码二进制资源内容。 **取值范围：** 不涉及。 | | mime_type | String | **参数解释：** 资源内容的 MIME 类型。 **取值范围：** 不涉及。 | | text | String | **参数解释：** 文本资源内容。 **取值范围：** 不涉及。 | | uri | String | **参数解释：** 资源内容的URI。 **取值范围：** 不涉及。 | 表10CodeInterpreterResultStructuredContent | 参数 | 参数类型 | 描述 | |:---|:---|:---| | execution_time | Integer | **参数解释：** 工具操作的执行时间。 **取值范围：** ≥0（单位：毫秒）。 | | exit_code | Integer | **参数解释：** 工具执行的退出代码。 **取值范围：** 0表示成功执行，非0表示执行异常，具体错误码含义取决于执行的语言和命令。 | | stderr | String | **参数解释：** 工具执行时的标准错误输出。 **取值范围：** 不涉及。 | | stdout | String | **参数解释：** 工具执行后的标准输出。 **取值范围：** 不涉及。 | **状态码：401** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**: 错误码。 **取值范围**: 满足正则规则\^AgentArts.0401\\d{4}$。 | | error_msg | String | **参数解释**： 错误详细信息。 **取值范围**： 不涉及。 | #### 请求示例 ``` POST /v1/code-interpreters/{code_interpreter_name}/invoke { "operate_type" : "execute_code", "arguments" : { "clear_context" : false, "code" : "print('Hello world!')", "language" : "python" } } ``` #### 响应示例 **状态码：200** OK ``` { "result" : { "content" : [ { "type" : "text", "data" : null, "description" : null, "mime_type" : null, "name" : null, "size" : null, "text" : "output content", "uri" : null, "resource" : { "type" : "text", "blob" : null, "mime_type" : null, "text" : null, "uri" : null } } ], "is_error" : false } } ``` **状态码：400** 请求参数错误。 ``` { "error_code" : "AgentArts.04010001", "error_msg" : "arguments -> code: Input should be a valid string; arguments -> write_contents: Field required" } ``` **状态码：401** 未授权（认证令牌缺失、无效或已过期）。 ``` { "error_code" : "AgentArts.04010002", "error_msg" : "Authentication failed" } ``` **状态码：404** 资源不存在。 ``` { "error_code" : "AgentArts.04010004", "error_msg" : "Session s-001 not found" } ``` **状态码：408** 请求超时。 ``` { "result" : { "content" : [ { "type" : "text", "text" : "Execution timed out after 900 seconds" } ], "is_error" : true } } ``` **状态码：413** 请求体过大。 ``` { "error_code" : "REQUEST_TOO_LARGE", "error_msg" : "Request body too large. Maximum allowed size is 104857600 bytes." } ``` **状态码：429** 请求频率超限。 ``` { "error_code" : "AgentArts.04010006", "error_msg" : "Too many pending requests for this session" } ``` **状态码：500** 服务内部错误。 ``` { "error_code" : "AgentArts.04010000", "error_msg" : "Internal server error" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | OK | | 400 | 请求参数错误。 | | 401 | 未授权（认证令牌缺失、无效或已过期）。 | | 404 | 资源不存在。 | | 408 | 请求超时。 | | 413 | 请求体过大。 | | 429 | 请求频率超限。 | | 500 | 服务内部错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。