{"meta":{"title":"通过 API 使用 Copilot 云代理","intro":"可以使用 REST API 直接启动和管理 Copilot cloud agent 任务，并使用 REST 和 GraphQL API 将问题分配给Copilot。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/copilot","title":"GitHub Copilot"},{"href":"/zh/copilot/how-tos","title":"操作方法"},{"href":"/zh/copilot/how-tos/use-copilot-agents","title":"使用Copilot代理"},{"href":"/zh/copilot/how-tos/use-copilot-agents/cloud-agent","title":"Cloud agent"},{"href":"/zh/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-via-the-api","title":"通过 API 使用云代理"}],"documentType":"article"},"body":"# 通过 API 使用 Copilot 云代理\n\n可以使用 REST API 直接启动和管理 Copilot cloud agent 任务，并使用 REST 和 GraphQL API 将问题分配给Copilot。\n\n您可以使用代理任务 API 将 cloud agent 集成到您自己的工具和工作流中。 例如，可以启动新任务、列出现有任务或检查任务的状态。\n\n此外，您可以使用用于处理问题的 REST 和 GraphQL API 将问题分配给 Copilot。\n\n## 使用代理任务 API\n\n> \\[!NOTE]\n> 智能体任务 API 位于 公开预览，可能会发生变更。\n\n### Authentication\n\n代理任务 API 仅支持用户到服务器令牌。 您可以使用 personal access token、OAuth app 令牌或 GitHub App 用户到服务器令牌进行身份验证。\n\n不支持服务器到服务器令牌，例如 GitHub App 安装访问令牌。\n\n### 通过 API 启动任务\n\n要启动新cloud agent任务，请发送`POST`请求至`/agents/repos/{owner}/{repo}/tasks`。 唯一必需的参数是 `prompt`，这是代理的提示。\n\n```shell copy\ncurl -X POST \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks \\\n  -d '{\n    \"prompt\": \"Fix the login button on the homepage\",\n    \"base_ref\": \"main\"\n  }'\n```\n\n替换以下占位符值：\n\n* ```\n            `YOUR-TOKEN`：一个 personal access token 或 GitHub App 用户到服务器令牌。\n  ```\n* `OWNER`：存储库的帐户所有者。\n* `REPO`：存储库的名称。\n\n还可以在请求正文中包含以下可选参数：\n\n* `base_ref`：新分支和拉取请求的基分支。\n* `model`：用于任务的 AI 模型。 如果省略，将使用 auto model selection。 有关支持模型的详细信息，请参阅 [代理任务的 REST API 终结点](/zh/rest/agent-tasks/agent-tasks)。\n* `create_pull_request`：一个布尔值，用于确定是否为任务创建拉取请求。\n\n### 列出任务\n\n可以列出特定存储库或有权访问的所有存储库的任务。\n\n列出特定存储库的任务：\n\n```shell copy\ncurl -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks\n```\n\n要列出所有存储库中的任务，请执行以下步骤：\n\n```shell copy\ncurl -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/tasks\n```\n\n### 检查任务的状态\n\n若要检查特定任务的状态，请使用任务 ID 发送请求 `GET` ：\n\n```shell copy\ncurl -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks/TASK-ID\n```\n\n将 `TASK-ID` 替换为您要检查的任务的 ID。 创建任务或列表任务时，可以从响应中获取此 ID。 响应包括任务的当前`state`，可以是`queued`、`in_progress`、`completed`、`failed`、`idle`、`waiting_for_user`、`timed_out`或`cancelled`之一。\n\n## 使用问题 API\n\n> \\[!NOTE]\n> 此功能目前处于公开预览，可能会发生更改。\n\n可以使用 GraphQL API 或 REST API 将问题分配给 Copilot。 这两个 API 都支持可选的代理任务分配输入来定制任务：\n\n| GraphQL 参数           | REST 参数               | Description         |\n| -------------------- | --------------------- | ------------------- |\n| `targetRepositoryId` | `target_repo`         | Copilot 将在其中工作的存储库  |\n| `baseRef`            | `base_branch`         |                     |\n| Copilot 将从其分支的分支     |                       |                     |\n| `customInstructions` | `custom_instructions` |                     |\n| Copilot 的其他说明        |                       |                     |\n| `customAgent`        | `custom_agent`        | 要用于任务的 custom agent |\n| `model`              | `model`               | 要使用的 Copilot 模型     |\n\n### 使用 GraphQL API\n\n> \\[!NOTE]\n> 必须在 `GraphQL-Features` 标头中包含值 `issues_copilot_assignment_api_support` 和 `coding_agent_model_selection`。\n\n可以使用以下 GraphQL 变更操作将问题分配给 Copilot：\n\n* [`updateIssue`](/zh/graphql/reference/mutations#updateissue)\n* [`createIssue`](/zh/graphql/reference/mutations#createissue)\n* [`addAssigneesToAssignable`](/zh/graphql/reference/mutations#addassigneestoassignable)\n* [`replaceActorsForAssignable`](/zh/graphql/reference/mutations#replaceactorsforassignable)\n\n#### 创建和分配新议题\n\n1. 请确保使用用户令牌（例如 personal access token ，或 GitHub App 用户到服务器令牌）通过 API 进行身份验证。\n\n   > \\[!NOTE]\n   > 如果使用fine-grained personal access token，则需要以下权限才能将Copilot分配给一个问题：\n   >\n   > * 对元数据的读取访问权限\n   > * 对操作、内容、问题和拉取请求的读写权限\n   >\n   > 如果使用personal access token (classic)，则需要`repo` 范围来将Copilot分配到一个问题中。\n\n2. 通过检查 GraphQL API 中存储库的 Copilot cloud agent 是否包含 `suggestedActors`，验证存储库中是否启用了 Copilot。 将 `octo-org` 替换为仓库所有者，将 `octo-repo` 替换为仓库名称。\n\n   ```graphql copy\n   query {\n     repository(owner: \"octo-org\", name: \"octo-repo\") {\n       suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {\n         nodes {\n           login\n           __typename\n\n           ... on Bot {\n             id\n           }\n\n           ... on User {\n             id\n           }\n         }\n       }\n     }\n   }\n   ```\n\n   如果 Copilot cloud agent 对用户和存储库均已启用，则从查询返回的第一个节点将具有 `login` 值 `copilot-swe-agent`。\n\n3. 记下此登录名的 `id` 值。\n\n4. 获取你想要在其中创建议题的仓库的 GraphQL 全局 ID，将 `octo-org` 替换为仓库所有者，将 `octo-repo` 替换为仓库名称。\n\n   ```graphql copy\n   query {\n     repository(owner: \"octo-org\", name: \"octo-repo\") {\n       id\n     }\n   }\n   ```\n\n5. 使用 `createIssue` 突变创建议题。 将 `REPOSITORY_ID` 替换为上一步返回的 ID，并将 `BOT_ID` 替换为上上个步骤返回的 ID。 可以选择包含 `agentAssignment` 输入以自定义任务。\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     createIssue(input: {\n       repositoryId: \"REPOSITORY_ID\",\n       title: \"Implement comprehensive unit tests\",\n       body: \"DETAILS\",\n       assigneeIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Add comprehensive test coverage\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       issue {\n         id\n         title\n         assignees(first: 10) {\n           nodes {\n             login\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n#### 分配现有议题\n\n1. 请确保使用用户令牌（例如 personal access token ，或 GitHub App 用户到服务器令牌）通过 API 进行身份验证。\n\n2. 通过检查 GraphQL API 中存储库的 Copilot cloud agent 是否包含 `suggestedActors`，验证存储库中是否启用了 Copilot。 将 `octo-org` 替换为仓库所有者，将 `octo-repo` 替换为仓库名称。\n\n   ```graphql copy\n   query {\n     repository(owner: \"monalisa\", name: \"octocat\") {\n       suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {\n         nodes {\n           login\n           __typename\n\n           ... on Bot {\n             id\n           }\n\n           ... on User {\n             id\n           }\n         }\n       }\n     }\n   }\n   ```\n\n   如果 Copilot cloud agent 对用户和存储库均已启用，则从查询返回的第一个节点将具有 `login` 值 `copilot-swe-agent`。\n\n3. 提取要分配给 Copilot的问题的 GraphQL 全局 ID，将其 `monalisa` 替换为存储库所有者、 `octocat` 名称和 `9000` 问题编号。\n\n   ```graphql copy\n   query {\n     repository(owner: \"monalisa\", name: \"octocat\") {\n       issue(number: 9000) {\n         id\n         title\n       }\n     }\n   }\n   ```\n\n4. 使用 `replaceActorsForAssignable` 突变将现有问题分配给 Copilot。 将 `ISSUE_ID` 替换为上一步返回的 ID，将 `BOT_ID` 替换为前面步骤返回的 ID，并将 `REPOSITORY_ID` 替换为存储库 ID。 可以选择包含 `agentAssignment` 输入以自定义任务。\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     replaceActorsForAssignable(input: {\n       assignableId: \"ISSUE_ID\",\n       actorIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Fix the reported bug\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       assignable {\n         ... on Issue {\n           id\n           title\n           assignees(first: 10) {\n             nodes {\n               login\n             }\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n5. 或者，可以使用 `updateIssue` 变更来更新现有问题并将其分配给 Copilot。 将 `ISSUE_ID` 替换为问题 ID，将 `BOT_ID` 替换为机器人 ID。\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     updateIssue(input: {\n       id: \"ISSUE_ID\",\n       assigneeIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Update feature implementation\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       issue {\n         id\n         title\n         assignees(first: 10) {\n           nodes {\n             login\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n6. 还可以使用 `addAssigneesToAssignable` 突变将 Copilot 添加到现有问题中，同时保留其他被分配者。 将 `ISSUE_ID` 替换为问题 ID，将 `BOT_ID` 替换为机器人 ID。\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     addAssigneesToAssignable(input: {\n       assignableId: \"ISSUE_ID\",\n       assigneeIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Collaborate on this task\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       assignable {\n         ... on Issue {\n           id\n           title\n           assignees(first: 10) {\n             nodes {\n               login\n             }\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n### 使用 REST API\n\n您可以使用以下 REST API 终结点将问题分配给 Copilot:\n\n* [向问题添加被分配者](/zh/rest/issues/assignees#add-assignees-to-an-issue)\n* [创建问题](/zh/rest/issues/issues#create-an-issue)\n* [更新问题](/zh/rest/issues/issues#update-an-issue)\n\n#### 向现有问题添加被分配者\n\n```shell copy\ngh api \\\n  --method POST \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees \\\n  --input - <<< '{\n  \"assignees\": [\"copilot-swe-agent[bot]\"],\n  \"agent_assignment\": {\n    \"target_repo\": \"OWNER/REPO\",\n    \"base_branch\": \"main\",\n    \"custom_instructions\": \"\",\n    \"custom_agent\": \"\",\n    \"model\": \"\"\n  }\n}'\n```\n\n#### 创建新问题\n\n```shell copy\ngh api \\\n  --method POST \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /repos/OWNER/REPO/issues \\\n  --input - <<< '{\n  \"title\": \"Issue title\",\n  \"body\": \"Issue description.\",\n  \"assignees\": [\"copilot-swe-agent[bot]\"],\n  \"agent_assignment\": {\n    \"target_repo\": \"OWNER/REPO\",\n    \"base_branch\": \"main\",\n    \"custom_instructions\": \"\",\n    \"custom_agent\": \"\",\n    \"model\": \"\"\n  }\n}'\n```\n\n#### 更新现有问题\n\n```shell copy\ngh api \\\n  --method PATCH \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /repos/OWNER/REPO/issues/ISSUE_NUMBER \\\n  --input - <<< '{\n  \"assignees\": [\"copilot-swe-agent[bot]\"],\n  \"agent_assignment\": {\n    \"target_repo\": \"OWNER/REPO\",\n    \"base_branch\": \"main\",\n    \"custom_instructions\": \"\",\n    \"custom_agent\": \"\",\n    \"model\": \"\"\n  }\n}'\n```\n\n## 延伸阅读\n\n* [代理任务的 REST API 终结点](/zh/rest/agent-tasks/agent-tasks)\n* [关于 GitHub Copilot 云代理](/zh/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [启动GitHub Copilot会话](/zh/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions)"}