# 通过 API 使用 Copilot 云代理

可以使用 REST API 直接启动和管理 Copilot cloud agent 任务，并使用 REST 和 GraphQL API 将问题分配给Copilot。

您可以使用代理任务 API 将 cloud agent 集成到您自己的工具和工作流中。 例如，可以启动新任务、列出现有任务或检查任务的状态。

此外，您可以使用用于处理问题的 REST 和 GraphQL API 将问题分配给 Copilot。

## 使用代理任务 API

> \[!NOTE]
> 智能体任务 API 位于 公开预览，可能会发生变更。

### Authentication

代理任务 API 仅支持用户到服务器令牌。 您可以使用 personal access token、OAuth app 令牌或 GitHub App 用户到服务器令牌进行身份验证。

不支持服务器到服务器令牌，例如 GitHub App 安装访问令牌。

### 通过 API 启动任务

要启动新cloud agent任务，请发送`POST`请求至`/agents/repos/{owner}/{repo}/tasks`。 唯一必需的参数是 `prompt`，这是代理的提示。

```shell copy
curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -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"
  }'
```

替换以下占位符值：

* ```
            `YOUR-TOKEN`：一个 personal access token 或 GitHub App 用户到服务器令牌。
  ```
* `OWNER`：存储库的帐户所有者。
* `REPO`：存储库的名称。

还可以在请求正文中包含以下可选参数：

* `base_ref`：新分支和拉取请求的基分支。
* `model`：用于任务的 AI 模型。 如果省略，将使用 auto model selection。 有关支持模型的详细信息，请参阅 [代理任务的 REST API 终结点](/zh/rest/agent-tasks/agent-tasks)。
* `create_pull_request`：一个布尔值，用于确定是否为任务创建拉取请求。

### 列出任务

可以列出特定存储库或有权访问的所有存储库的任务。

列出特定存储库的任务：

```shell copy
curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks
```

要列出所有存储库中的任务，请执行以下步骤：

```shell copy
curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/tasks
```

### 检查任务的状态

若要检查特定任务的状态，请使用任务 ID 发送请求 `GET` ：

```shell copy
curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks/TASK-ID
```

将 `TASK-ID` 替换为您要检查的任务的 ID。 创建任务或列表任务时，可以从响应中获取此 ID。 响应包括任务的当前`state`，可以是`queued`、`in_progress`、`completed`、`failed`、`idle`、`waiting_for_user`、`timed_out`或`cancelled`之一。

## 使用问题 API

> \[!NOTE]
> 此功能目前处于公开预览，可能会发生更改。

可以使用 GraphQL API 或 REST API 将问题分配给 Copilot。 这两个 API 都支持可选的代理任务分配输入来定制任务：

| GraphQL 参数           | REST 参数               | Description         |
| -------------------- | --------------------- | ------------------- |
| `targetRepositoryId` | `target_repo`         | Copilot 将在其中工作的存储库  |
| `baseRef`            | `base_branch`         |                     |
| Copilot 将从其分支的分支     |                       |                     |
| `customInstructions` | `custom_instructions` |                     |
| Copilot 的其他说明        |                       |                     |
| `customAgent`        | `custom_agent`        | 要用于任务的 custom agent |
| `model`              | `model`               | 要使用的 Copilot 模型     |

### 使用 GraphQL API

> \[!NOTE]
> 必须在 `GraphQL-Features` 标头中包含值 `issues_copilot_assignment_api_support` 和 `coding_agent_model_selection`。

可以使用以下 GraphQL 变更操作将问题分配给 Copilot：

* [`updateIssue`](/zh/graphql/reference/mutations#updateissue)
* [`createIssue`](/zh/graphql/reference/mutations#createissue)
* [`addAssigneesToAssignable`](/zh/graphql/reference/mutations#addassigneestoassignable)
* [`replaceActorsForAssignable`](/zh/graphql/reference/mutations#replaceactorsforassignable)

#### 创建和分配新议题

1. 请确保使用用户令牌（例如 personal access token ，或 GitHub App 用户到服务器令牌）通过 API 进行身份验证。

   > \[!NOTE]
   > 如果使用fine-grained personal access token，则需要以下权限才能将Copilot分配给一个问题：
   >
   > * 对元数据的读取访问权限
   > * 对操作、内容、问题和拉取请求的读写权限
   >
   > 如果使用personal access token (classic)，则需要`repo` 范围来将Copilot分配到一个问题中。

2. 通过检查 GraphQL API 中存储库的 Copilot cloud agent 是否包含 `suggestedActors`，验证存储库中是否启用了 Copilot。 将 `octo-org` 替换为仓库所有者，将 `octo-repo` 替换为仓库名称。

   ```graphql copy
   query {
     repository(owner: "octo-org", name: "octo-repo") {
       suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {
         nodes {
           login
           __typename

           ... on Bot {
             id
           }

           ... on User {
             id
           }
         }
       }
     }
   }
   ```

   如果 Copilot cloud agent 对用户和存储库均已启用，则从查询返回的第一个节点将具有 `login` 值 `copilot-swe-agent`。

3. 记下此登录名的 `id` 值。

4. 获取你想要在其中创建议题的仓库的 GraphQL 全局 ID，将 `octo-org` 替换为仓库所有者，将 `octo-repo` 替换为仓库名称。

   ```graphql copy
   query {
     repository(owner: "octo-org", name: "octo-repo") {
       id
     }
   }
   ```

5. 使用 `createIssue` 突变创建议题。 将 `REPOSITORY_ID` 替换为上一步返回的 ID，并将 `BOT_ID` 替换为上上个步骤返回的 ID。 可以选择包含 `agentAssignment` 输入以自定义任务。

   ```shell copy
   gh api graphql -f query='mutation {
     createIssue(input: {
       repositoryId: "REPOSITORY_ID",
       title: "Implement comprehensive unit tests",
       body: "DETAILS",
       assigneeIds: ["BOT_ID"],
       agentAssignment: {
         targetRepositoryId: "REPOSITORY_ID",
         baseRef: "main",
         customInstructions: "Add comprehensive test coverage",
         customAgent: "",
         model: ""
       }
     }) {
       issue {
         id
         title
         assignees(first: 10) {
           nodes {
             login
           }
         }
       }
     }
   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'
   ```

#### 分配现有议题

1. 请确保使用用户令牌（例如 personal access token ，或 GitHub App 用户到服务器令牌）通过 API 进行身份验证。

2. 通过检查 GraphQL API 中存储库的 Copilot cloud agent 是否包含 `suggestedActors`，验证存储库中是否启用了 Copilot。 将 `octo-org` 替换为仓库所有者，将 `octo-repo` 替换为仓库名称。

   ```graphql copy
   query {
     repository(owner: "monalisa", name: "octocat") {
       suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {
         nodes {
           login
           __typename

           ... on Bot {
             id
           }

           ... on User {
             id
           }
         }
       }
     }
   }
   ```

   如果 Copilot cloud agent 对用户和存储库均已启用，则从查询返回的第一个节点将具有 `login` 值 `copilot-swe-agent`。

3. 提取要分配给 Copilot的问题的 GraphQL 全局 ID，将其 `monalisa` 替换为存储库所有者、 `octocat` 名称和 `9000` 问题编号。

   ```graphql copy
   query {
     repository(owner: "monalisa", name: "octocat") {
       issue(number: 9000) {
         id
         title
       }
     }
   }
   ```

4. 使用 `replaceActorsForAssignable` 突变将现有问题分配给 Copilot。 将 `ISSUE_ID` 替换为上一步返回的 ID，将 `BOT_ID` 替换为前面步骤返回的 ID，并将 `REPOSITORY_ID` 替换为存储库 ID。 可以选择包含 `agentAssignment` 输入以自定义任务。

   ```shell copy
   gh api graphql -f query='mutation {
     replaceActorsForAssignable(input: {
       assignableId: "ISSUE_ID",
       actorIds: ["BOT_ID"],
       agentAssignment: {
         targetRepositoryId: "REPOSITORY_ID",
         baseRef: "main",
         customInstructions: "Fix the reported bug",
         customAgent: "",
         model: ""
       }
     }) {
       assignable {
         ... on Issue {
           id
           title
           assignees(first: 10) {
             nodes {
               login
             }
           }
         }
       }
     }
   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'
   ```

5. 或者，可以使用 `updateIssue` 变更来更新现有问题并将其分配给 Copilot。 将 `ISSUE_ID` 替换为问题 ID，将 `BOT_ID` 替换为机器人 ID。

   ```shell copy
   gh api graphql -f query='mutation {
     updateIssue(input: {
       id: "ISSUE_ID",
       assigneeIds: ["BOT_ID"],
       agentAssignment: {
         targetRepositoryId: "REPOSITORY_ID",
         baseRef: "main",
         customInstructions: "Update feature implementation",
         customAgent: "",
         model: ""
       }
     }) {
       issue {
         id
         title
         assignees(first: 10) {
           nodes {
             login
           }
         }
       }
     }
   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'
   ```

6. 还可以使用 `addAssigneesToAssignable` 突变将 Copilot 添加到现有问题中，同时保留其他被分配者。 将 `ISSUE_ID` 替换为问题 ID，将 `BOT_ID` 替换为机器人 ID。

   ```shell copy
   gh api graphql -f query='mutation {
     addAssigneesToAssignable(input: {
       assignableId: "ISSUE_ID",
       assigneeIds: ["BOT_ID"],
       agentAssignment: {
         targetRepositoryId: "REPOSITORY_ID",
         baseRef: "main",
         customInstructions: "Collaborate on this task",
         customAgent: "",
         model: ""
       }
     }) {
       assignable {
         ... on Issue {
           id
           title
           assignees(first: 10) {
             nodes {
               login
             }
           }
         }
       }
     }
   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'
   ```

### 使用 REST API

您可以使用以下 REST API 终结点将问题分配给 Copilot:

* [向问题添加被分配者](/zh/rest/issues/assignees#add-assignees-to-an-issue)
* [创建问题](/zh/rest/issues/issues#create-an-issue)
* [更新问题](/zh/rest/issues/issues#update-an-issue)

#### 向现有问题添加被分配者

```shell copy
gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees \
  --input - <<< '{
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "custom_agent": "",
    "model": ""
  }
}'
```

#### 创建新问题

```shell copy
gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues \
  --input - <<< '{
  "title": "Issue title",
  "body": "Issue description.",
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "custom_agent": "",
    "model": ""
  }
}'
```

#### 更新现有问题

```shell copy
gh api \
  --method PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER \
  --input - <<< '{
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "custom_agent": "",
    "model": ""
  }
}'
```

## 延伸阅读

* [代理任务的 REST API 终结点](/zh/rest/agent-tasks/agent-tasks)
* [关于 GitHub Copilot 云代理](/zh/copilot/concepts/agents/cloud-agent/about-cloud-agent)
* [启动GitHub Copilot会话](/zh/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions)