通过 API 使用 Copilot 云代理

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

谁可以使用此功能？

拥有 Copilot业务 或 Copilot Enterprise 计划的组织。

在本文中

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

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

使用代理任务 API

注意

智能体任务 API 位于 公开预览，可能会发生变更。

Authentication

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

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

通过 API 启动任务

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

Shell
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 模型。 如果省略，将使用 自动模型选择。 有关支持模型的详细信息，请参阅 代理任务的 REST API 终结点。
  • create_pull_request：一个布尔值，用于确定是否为任务创建拉取请求。

列出任务

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

列出特定存储库的任务：

Shell
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
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
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

注意

此功能目前处于公开预览，可能会发生更改。

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

GraphQL 参数REST 参数Description
targetRepositoryIdtarget_repoCopilot 将在其中工作的存储库
baseRefbase_branch
Copilot 将从其分支的分支
customInstructionscustom_instructions
Copilot 的其他说明
customAgentcustom_agent要用于任务的 自定义智能体
modelmodel要使用的 Copilot 模型

使用 GraphQL API

注意

必须在 GraphQL-Features 标头中包含值 issues_copilot_assignment_api_support 和 coding_agent_model_selection。

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

创建和分配新议题

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

    注意

    如果使用fine-grained personal access token，则需要以下权限才能将Copilot分配给一个问题：

    • 对元数据的读取访问权限
    • 对操作、内容、问题和拉取请求的读写权限

    如果使用personal access token (classic)，则需要repo 范围来将Copilot分配到一个问题中。

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

    GraphQL
    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云代理 对用户和存储库均已启用，则从查询返回的第一个节点将具有 login 值 copilot-swe-agent。

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

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

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

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

    Shell
    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云代理 是否包含 suggestedActors，验证存储库中是否启用了 Copilot。 将 octo-org 替换为仓库所有者，将 octo-repo 替换为仓库名称。

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

        ... on Bot {
          id
        }

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

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

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

    GraphQL
    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
    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
    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
    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:

向现有问题添加被分配者

Shell
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
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
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": ""
  }
}'

延伸阅读