Agent tasks REST API

创建云端任务、查询运行状态，并核对用户 token、权限和默认 PR 行为。

This page has not been translated into English yet. The original Chinese version is shown below.

Agent tasks API 可从自己的工具启动和查询 cloud agent 任务，当前为 public preview。它与通过 Issues API 分配 Issue 是不同入口，权限和请求参数不能混用。

认证与许可

入门指南支持用户身份 token：PAT、OAuth app token 或 GitHub App user-to-server token。GitHub App installation token 等 server-to-server token 不支持。

当前 REST 端点参考对 fine-grained PAT 和 GitHub App user access token 规定：读取任务需要仓库 Agent tasks: read，创建需要 Agent tasks: read and write。创建端点还明确限 Copilot Business 或 Copilot Enterprise 用户；入门教程未突出此限制，不应据此推定所有付费个人套餐都能使用创建 API。

创建任务

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks \
  -d '{
    "prompt": "Fix the login button on the homepage",
    "base_ref": "main",
    "create_pull_request": true
  }'

替换 token、仓库 owner/name 和实际 base branch。该请求会启动真实任务；本例明确要求创建 PR。

入门页示例仍使用 2022-11-28 API 版本头，当前端点参考使用 2026-03-10；本页按端点参考列出，不把两者静默视为完全相同版本。

请求字段	规则
`prompt`	唯一必填字段，任务说明
`model`	可选；省略时采用 Auto。可接受值受套餐、策略与 API 当前列表影响
`custom_agent`	可选 profile 文件标识，如 performance-optimizer.agent.md 对应 performance-optimizer
`create_pull_request`	默认 false；需要 PR 时明确设为 true
`base_ref`	新分支或 PR 的起点
`head_ref`	已有分支；与 base_ref 一起提供时，查询对应 open PR 上下文并向 head_ref 提交，而不是创建新分支

模型 API 的字符串列表与网页显示名称不能互换使用。官方各页模型清单存在差异，未验证具体值时可省略 model，不复制 UI 的名称作为请求值。

查询入口

请求	用途
`GET /agents/repos/{owner}/{repo}/tasks`	查询指定仓库任务
`GET /agents/tasks`	查询当前认证用户的任务
`GET /agents/repos/{owner}/{repo}/tasks/{task_id}`	按仓库路径查询单个任务与会话
`GET /agents/tasks/{task_id}`	按任务 ID 查询任务与会话

查询使用与创建一致的认证和版本头。任务 ID 从创建或列表响应读取，不要用 PR 编号替代。

列表默认每页 30 条，第 1 页；per_page 最大 100。默认 sort=updated_at、direction=desc，也支持 created_at 和 asc。is_archived 默认 false，仅返回未归档任务；true 仅查归档任务。

state 支持逗号分隔状态列表，since 为 ISO 8601 更新时间下界。仓库列表还支持 creator_id 数组；不要把该参数外推到用户级列表。

解析状态和结果

状态枚举为 queued、in_progress、completed、failed、idle、waiting_for_user、timed_out、cancelled。保存原始状态，不要把任何停止更新的任务都当成 completed。

列表响应含 tasks；任务的 artifacts 可为 pull 或 branch，不保证总有 PR。详情中的 sessions 可包含提示、模型、分支、时间、usage 和错误消息。Usage 类型可能为 ai_credits 或 premium_requests，应按 type 解释 amount，不能一律当作货币金额。

创建成功返回 201，读取成功返回 200。认证、权限、资源和参数问题分别检查实际 HTTP 状态及响应：例如 401、403、404、422；并非每个端点都列出所有错误状态。

通过 Issue 发起任务见Issues API，人工管理任务见会话管理。