Agent tasks REST API

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

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，人工管理任务见会话管理。