--- title: "Create an agent task" method: POST path: "/tasks" tags: ["Tasks"] --- # Create an agent task `POST /tasks` Creates a model task. Provide [text](https://docs.linxueyuan.online/guides/text) or [image](https://docs.linxueyuan.online/guides/images) inputs to generate [text](https://docs.linxueyuan.online/guides/text) or [JSON](https://docs.linxueyuan.online/guides/structured-outputs) outputs. Have the model call your own [custom code](https://docs.linxueyuan.online/guides/function-calling) or use built-in [tools](https://docs.linxueyuan.online/guides/tools) like [web search](https://docs.linxueyuan.online/guides/tools-web-search) or [file search](https://docs.linxueyuan.online/guides/tools-file-search) to use your own data as input for the model's task. ## Request body - CreateTask — Request payload for POST /tasks. Maps to the CreateTask Pydantic model in server. - `user_message_content` union, required — 消息内容，字符串或内容项数组，工具协议兼容的 message_content（保留字段）。 - string - ContentItem[] — 内容项数组。 - union — A single content item within a message. - object - `type` 'text' | 'input_text' | 'output_text' | 'reasoning_text' | 'summary_text' | 'refusal', required — 文本内容类型。 - `text` string, required — 文本内容。 - `id` integer — 可选的内容引用 ID。 - `tags` string[] — 可选标签，用于标记内容来源或用途（如 "added_by_reference_manager"）。 - `annotations` Annotation[] — 文本注释（如引用、链接、文件路径等），与后端 Annotation 模型一致。 - union - … - `logprobs` LogProb[] — 每个 token 的对数概率信息（可选）。 - `token` string, required - `logprob` number, required - `bytes` integer[], required - `top_logprobs` TopLogProb[], required - … - object - `type` 'image' | 'input_image' | 'output_image' | 'image_url', required — 图片内容类型。 - `image_url` ImageURL, required - `url` string, uri, required — 图片的可访问 URL。 - `detail` 'low' | 'high' | 'auto', nullable — 清晰度等级，可选 low/high/auto。 - object - `type` 'input_audio' | 'output_audio' | 'audio', required — 音频内容类型。 - `input_audio` InputAudio, required - `data` string, required — Base64-encoded audio bytes - `format` 'wav' | 'mp3', required - object - `type` 'file', required — 文件内容类型。 - `file` FileDetail, required - `file_data` string — Optional Base64-encoded file content - `file_url` string, required — 远程文件的可访问 URL；与 file_data 二选一，可同时提供以便存档。 - `filename` string, required — 文件名（含扩展名），用于渲染与调试追踪。 - `stream` boolean, required — 是否启用流式（SSE）返回；true 则以 text/event-stream 推送 Task 事件。 - `structured_output` object — 期望的结构化输出 JSON Schema；仅非流式模式有效，流式模式下将被忽略。 - `client_id` string — 调用方客户端标识（如 AIME）。 - `request_id` string — 请求链路唯一 ID；便于将复杂调用串联在一起。 - `session_id` string — 会话 ID；用于跨多轮交互复用上下文。 - `task_id` string — 任务 ID；用于区分主任务与子任务。 - `user_id` string — 终端用户 ID。 - `agent_config` AgentConfig — The Agent configuration used by the server. - `agent_id` string, required — Agent 唯一标识（目录名）。 - `name` string, required — Agent 名称。 - `description` string, required — Agent 描述。 - `developer_prompt` string, required — 主系统提示词（开发者指令）。 - `code_for_agent` string, required — 注入到 Agent 侧的代码片段。 - `code_for_interpreter` string, required — 注入到代码解释器侧的代码片段。 - `allowed_tools` string[] — 默认允许使用的工具。 - `tool_mcp_config` object — MCP 服务器配置（工具来源）。 - `model` string, required — 主模型名称。 - `max_model_length` integer, required — 模型上下文最大 tokens。 - `max_response_length` integer, required — 模型生成的最大 tokens。 - `compress_prompt` string — 上下文压缩时使用的系统提示词。 - `compress_model` string — 用于压缩上下文的模型名称。 - `compress_threshold_token_ratio` number — 触发上下文压缩的 token 比例阈值。 - `inference_args` object — 默认推理参数覆盖项。 - `builtin_tools` ToolData[] — 内置工具集合（含 CodeInterpreter/Task 等）。 - `type` 'function', required — 工具类型，此处固定为 function。 - `function` FunctionDefinition, required - `name` string, required — 工具/函数名称（唯一标识）。 - `description` string — 函数的用途说明。 - `parameters` object, required — JSON Schema for the function parameters. - `strict` boolean — 是否启用严格参数校验。 - `code_interpreter_config` object — 代码解释器连接配置（Jupyter）。 - `builtin_subagents` object[] — 内置子代理列表（名称/工具/提示词等）。 - `allowed_tools` string[] — 允许使用的工具白名单；为 null 允许全部，空数组表示禁止所有。 - `disallowed_tools` string[] — 禁用的工具黑名单；为 null 或空数组不生效。 - `allowed_subagents` string[] — 允许使用的子代理白名单；为 null 允许全部，空数组禁止所有。 - `stop_tools` string[] — 命中则停止代理循环的工具名列表；为 null 或空数组不生效。 - `client_tools` ToolData[] — 客户端自带工具定义；命中后会停止由服务端执行，等待客户端完成。 - `type` 'function', required — 工具类型，此处固定为 function。 - `function` FunctionDefinition, required - `name` string, required — 工具/函数名称（唯一标识）。 - `description` string — 函数的用途说明。 - `parameters` object, required — JSON Schema for the function parameters. - `strict` boolean — 是否启用严格参数校验。 - `history_messages` OutputItem[] — 历史对话消息，用于提供上下文。 - union — An output item produced by the agent/model. - object - `type` 'reasoning', required — 推理项类型标识。 - `id` string, required — 推理项 ID。 - `summary` TextContentItem[], required — 推理摘要内容（结构化）。 - `type` 'text' | 'input_text' | 'output_text' | 'reasoning_text' | 'summary_text' | 'refusal', required — 文本内容类型。 - `text` string, required — 文本内容。 - `id` integer — 可选的内容引用 ID。 - `tags` string[] — 可选标签，用于标记内容来源或用途（如 "added_by_reference_manager"）。 - `annotations` Annotation[] — 文本注释（如引用、链接、文件路径等），与后端 Annotation 模型一致。 - union - … - `logprobs` LogProb[] — 每个 token 的对数概率信息（可选）。 - `token` string, required - `logprob` number, required - `bytes` integer[], required - `top_logprobs` TopLogProb[], required - … - `content` TextContentItem[] — 推理详细内容（可选）。 - `type` 'text' | 'input_text' | 'output_text' | 'reasoning_text' | 'summary_text' | 'refusal', required — 文本内容类型。 - `text` string, required — 文本内容。 - `id` integer — 可选的内容引用 ID。 - `tags` string[] — 可选标签，用于标记内容来源或用途（如 "added_by_reference_manager"）。 - `annotations` Annotation[] — 文本注释（如引用、链接、文件路径等），与后端 Annotation 模型一致。 - union - … - `logprobs` LogProb[] — 每个 token 的对数概率信息（可选）。 - `token` string, required - `logprob` number, required - `bytes` integer[], required - `top_logprobs` TopLogProb[], required - … - `status` 'in_progress' | 'completed' | 'incomplete' — 状态。 - object - `type` 'message', required — 消息条目类型标识。 - `id` string — 消息 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 消息生成状态。 - `role` 'user' | 'assistant' | 'system' | 'developer', required — 消息角色。 - `name` string — 角色名称（可选）。 - `message_content` union, required — 消息内容，字符串或内容项数组，工具协议兼容的 message_content（保留字段）。 - string - ContentItem[] — 内容项数组。 - union — A single content item within a message. - … - `block_list` object[] — 渲染块列表（图表/表格等富媒体）。 - object - `type` 'tool_call', required — 工具调用条目类型标识。 - `id` string — 工具调用条目 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 调用状态。 - `call_id` string, required — 工具调用唯一 ID（跨事件关联）。 - `name` string, required — 工具名称。 - `arguments` string, required — 工具调用参数（JSON 字符串）。 - `language` 'json' | 'yaml' | 'python' | 'javascript' — 参数语言标注（可选）。 - object - `type` 'tool_result', required — 工具结果条目类型标识。 - `id` string — 工具结果条目 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 结果状态。 - `call_id` string, required — 对应的工具调用 ID。 - `message_content` union, required — 消息内容，字符串或内容项数组，工具协议兼容的 message_content（保留字段）。 - string - ContentItem[] — 内容项数组。 - union — A single content item within a message. - … - `block_list` object[], required — 工具结果的渲染块列表。 - `thought_messages` OutputItem[] — 隐藏的助手思考内容（不可见思考轨迹），如有将并入上下文。 - union — An output item produced by the agent/model. - object - `type` 'reasoning', required — 推理项类型标识。 - `id` string, required — 推理项 ID。 - `summary` TextContentItem[], required — 推理摘要内容（结构化）。 - `type` 'text' | 'input_text' | 'output_text' | 'reasoning_text' | 'summary_text' | 'refusal', required — 文本内容类型。 - `text` string, required — 文本内容。 - `id` integer — 可选的内容引用 ID。 - `tags` string[] — 可选标签，用于标记内容来源或用途（如 "added_by_reference_manager"）。 - `annotations` Annotation[] — 文本注释（如引用、链接、文件路径等），与后端 Annotation 模型一致。 - union - … - `logprobs` LogProb[] — 每个 token 的对数概率信息（可选）。 - `token` string, required - `logprob` number, required - `bytes` integer[], required - `top_logprobs` TopLogProb[], required - … - `content` TextContentItem[] — 推理详细内容（可选）。 - `type` 'text' | 'input_text' | 'output_text' | 'reasoning_text' | 'summary_text' | 'refusal', required — 文本内容类型。 - `text` string, required — 文本内容。 - `id` integer — 可选的内容引用 ID。 - `tags` string[] — 可选标签，用于标记内容来源或用途（如 "added_by_reference_manager"）。 - `annotations` Annotation[] — 文本注释（如引用、链接、文件路径等），与后端 Annotation 模型一致。 - union - … - `logprobs` LogProb[] — 每个 token 的对数概率信息（可选）。 - `token` string, required - `logprob` number, required - `bytes` integer[], required - `top_logprobs` TopLogProb[], required - … - `status` 'in_progress' | 'completed' | 'incomplete' — 状态。 - object - `type` 'message', required — 消息条目类型标识。 - `id` string — 消息 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 消息生成状态。 - `role` 'user' | 'assistant' | 'system' | 'developer', required — 消息角色。 - `name` string — 角色名称（可选）。 - `message_content` union, required — 消息内容，字符串或内容项数组，工具协议兼容的 message_content（保留字段）。 - string - ContentItem[] — 内容项数组。 - union — A single content item within a message. - … - `block_list` object[] — 渲染块列表（图表/表格等富媒体）。 - object - `type` 'tool_call', required — 工具调用条目类型标识。 - `id` string — 工具调用条目 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 调用状态。 - `call_id` string, required — 工具调用唯一 ID（跨事件关联）。 - `name` string, required — 工具名称。 - `arguments` string, required — 工具调用参数（JSON 字符串）。 - `language` 'json' | 'yaml' | 'python' | 'javascript' — 参数语言标注（可选）。 - object - `type` 'tool_result', required — 工具结果条目类型标识。 - `id` string — 工具结果条目 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 结果状态。 - `call_id` string, required — 对应的工具调用 ID。 - `message_content` union, required — 消息内容，字符串或内容项数组，工具协议兼容的 message_content（保留字段）。 - string - ContentItem[] — 内容项数组。 - union — A single content item within a message. - … - `block_list` object[], required — 工具结果的渲染块列表。 - `inference_args` object — 推理参数覆盖项（如温度、最大 tokens 等），具体字段由后端实现决定。 - `workspace_dir` string — 文件系统工作目录；供文件工具与代码解释器使用。 - `env` object — Agent 的运行时环境变量键值对。 - `log_dir` string — 日志输出目录。 - `rollout_save_dir` string — 回溯（rollout）结果保存目录。 - `return_rollout` boolean — 是否在最终结果中返回 rollout 事件集合。 - `include_compress_model_rollout` boolean — 是否包含上下文压缩模型的 rollout 结果。 - `include_subagent_rollout` boolean — 是否包含子 Agent 的 rollout 结果。 ## Response `200` OK - TaskResponse — Base JSON-RPC 2.0 message. - `jsonrpc` '2.0', required — JSON-RPC protocol version, always '2.0'. - `id` union — 请求/响应 ID，由客户端生成或服务器透传；可为字符串、整数或 null。 - string - integer - `result` TaskObject — The task object returned in JSON-RPC result. - `object` 'task', required — 固定为 task。 - `id` string, required — 任务 ID。 - `session_id` string, required — 会话 ID。 - `user_id` string, required — 用户 ID。 - `status` 'created' | 'queued' | 'working' | 'input-required' | 'paused' | 'completed' | 'canceled' | 'expired' | 'failed', required — 任务生命周期状态。 CREATED：任务已创建但尚未开始。 QUEUED：任务已排队，等待处理。 WORKING：任务正在处理中。 INPUT_REQUIRED：任务需要额外输入以继续。 PAUSED：任务已暂停，需恢复后继续。 COMPLETED：任务已成功完成。 CANCELED：任务已取消，不会继续处理。 EXPIRED：任务已过期，不会继续处理。 FAILED：任务处理失败，不会重试。 常见情况： 1. CREATED -> WORKING -> COMPLETED|FAILED|CANCELED|EXPIRED 2. CREATED -> WORKING -> INPUT_REQUIRED -> WORKING -> COMPLETED|FAILED|CANCELED|EXPIRED 3. CREATED -> WORKING -> PAUSED -> WORKING -> COMPLETED|FAILED|CANCELED|EXPIRED 4. CREATED -> QUEUED -> WORKING -> COMPLETED|FAILED|CANCELED|EXPIRED 5. CREATED -> QUEUED -> WORKING -> INPUT_REQUIRED -> WORKING -> COMPLETED|FAILED|CANCELED|EXPIRED 6. CREATED -> QUEUED -> WORKING -> PAUSED -> WORKING -> COMPLETED|FAILED|CANCELED|EXPIRED 取消情况： 1. CREATED -> CANCELED 2. CREATED -> WORKING -> CANCELED 3. CREATED -> QUEUED -> CANCELED 4. CREATED -> QUEUED -> WORKING -> CANCELED 5. CREATED -> QUEUED -> WORKING -> PAUSED -> CANCELED 6. CREATED -> QUEUED -> WORKING -> INPUT_REQUIRED -> CANCELED 过期情况： 1. CREATED -> WORKING -> EXPIRED 2. CREATED -> WORKING -> INPUT_REQUIRED -> EXPIRED 3. CREATED -> WORKING -> PAUSED -> EXPIRED 4. CREATED -> QUEUED -> EXPIRED 5. CREATED -> QUEUED -> WORKING -> EXPIRED 6. CREATED -> QUEUED -> WORKING -> INPUT_REQUIRED -> EXPIRED 7. CREATED -> QUEUED -> WORKING -> PAUSED -> EXPIRED - `created_at` integer, required — 任务创建时间（Unix 秒）。 - `output` OutputItem[], required — 模型/代理生成的输出条目集合（多类型）。 - union — An output item produced by the agent/model. - object - `type` 'reasoning', required — 推理项类型标识。 - `id` string, required — 推理项 ID。 - `summary` TextContentItem[], required — 推理摘要内容（结构化）。 - `type` 'text' | 'input_text' | 'output_text' | 'reasoning_text' | 'summary_text' | 'refusal', required — 文本内容类型。 - `text` string, required — 文本内容。 - `id` integer — 可选的内容引用 ID。 - `tags` string[] — 可选标签，用于标记内容来源或用途（如 "added_by_reference_manager"）。 - `annotations` Annotation[] — 文本注释（如引用、链接、文件路径等），与后端 Annotation 模型一致。 - … - `logprobs` LogProb[] — 每个 token 的对数概率信息（可选）。 - … - `content` TextContentItem[] — 推理详细内容（可选）。 - `type` 'text' | 'input_text' | 'output_text' | 'reasoning_text' | 'summary_text' | 'refusal', required — 文本内容类型。 - `text` string, required — 文本内容。 - `id` integer — 可选的内容引用 ID。 - `tags` string[] — 可选标签，用于标记内容来源或用途（如 "added_by_reference_manager"）。 - `annotations` Annotation[] — 文本注释（如引用、链接、文件路径等），与后端 Annotation 模型一致。 - … - `logprobs` LogProb[] — 每个 token 的对数概率信息（可选）。 - … - `status` 'in_progress' | 'completed' | 'incomplete' — 状态。 - object - `type` 'message', required — 消息条目类型标识。 - `id` string — 消息 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 消息生成状态。 - `role` 'user' | 'assistant' | 'system' | 'developer', required — 消息角色。 - `name` string — 角色名称（可选）。 - `message_content` union, required — 消息内容，字符串或内容项数组，工具协议兼容的 message_content（保留字段）。 - string - ContentItem[] — 内容项数组。 - … - `block_list` object[] — 渲染块列表（图表/表格等富媒体）。 - object - `type` 'tool_call', required — 工具调用条目类型标识。 - `id` string — 工具调用条目 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 调用状态。 - `call_id` string, required — 工具调用唯一 ID（跨事件关联）。 - `name` string, required — 工具名称。 - `arguments` string, required — 工具调用参数（JSON 字符串）。 - `language` 'json' | 'yaml' | 'python' | 'javascript' — 参数语言标注（可选）。 - object - `type` 'tool_result', required — 工具结果条目类型标识。 - `id` string — 工具结果条目 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 结果状态。 - `call_id` string, required — 对应的工具调用 ID。 - `message_content` union, required — 消息内容，字符串或内容项数组，工具协议兼容的 message_content（保留字段）。 - string - ContentItem[] — 内容项数组。 - … - `block_list` object[], required — 工具结果的渲染块列表。 - `usage` object — token 用量统计信息。 - `error` JSONRPCError — JSON-RPC error object. - `code` integer, required — 错误码（遵循 JSON-RPC 约定或服务端自定义）。 - `message` string, required — 错误信息。 - `data` union — 自定义错误数据，任意 JSON 值或 null。 - object - string - number - integer - boolean - `input_required` ToolCallItem - `type` 'tool_call', required — 工具调用条目类型标识。 - `id` string — 工具调用条目 ID。 - `status` 'in_progress' | 'completed' | 'incomplete' — 调用状态。 - `call_id` string, required — 工具调用唯一 ID（跨事件关联）。 - `name` string, required — 工具名称。 - `arguments` string, required — 工具调用参数（JSON 字符串）。 - `language` 'json' | 'yaml' | 'python' | 'javascript' — 参数语言标注（可选）。 - `metadata` object — 扩展元数据。 - `previous_task_id` string — 前置任务 ID（用于续写/衔接）。 - `rollouts` object[] — 任务推演/回溯事件集合（可选）。 - `error` JSONRPCError — JSON-RPC error object. - `code` integer, required — 错误码（遵循 JSON-RPC 约定或服务端自定义）。 - `message` string, required — 错误信息。 - `data` union — 自定义错误数据，任意 JSON 值或 null。 - object - string - number - integer - boolean --- [API](https://skmtc.net/stainless-api/apis/agentlin-api.md) · [All operations](https://skmtc.net/stainless-api/apis/agentlin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/agentlin-api/versions/be7769091980/schema)