Использование облачного агента Copilot через API

Вы можете запускать и управлять Copilot облачный агент задачами программно с помощью REST API.

Кто может использовать эту функцию?

Copilot облачный агент доступна для всех платных Copilot планов.

Агент доступен во всех репозиториях, хранящихся на GitHub, за исключением тех, которые принадлежат управляемые учетные записи пользователей и где он явно отключен.
Sign up for Copilot

В этой статье

Вы можете использовать API задач агента для интеграции Облачный агент в свои инструменты и рабочие процессы. Например, вы можете начать новую задачу, перечислить существующие задачи или проверить статус задачи.

Кроме того, вы можете использовать API REST и GraphQL для задач, чтобы назначить задачи на Copilot.

Использование API задач агента

Примечание.

API задач агента включен Публичный предварительный просмотр и подвержен изменениям.

Authentication

API задач агента поддерживает только токены между пользователями. Вы можете аутентифицироваться с помощью personal access tokenтокена или OAuth appGitHub 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: A или personal access tokenGitHub App токен пользователя-сервер.
  • OWNER: Владелец аккаунта репозитория.
  • REPO: Название репозитория.

Вы также можете включить следующие опциональные параметры в тело запроса:

  • base_ref: Базовая ветка для новой ветки и pull request.
  • model: Модель ИИ для выполнения задачи. Если опущено, выбор автоматической модели используется. Для получения дополнительной информации о поддерживаемых моделях см. AUTOTITLE.
  • create_pull_request: Булева величина, которая определяет, создавать ли 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

Проверка статуса задачи

Чтобы проверить статус конкретной задачи, отправьте 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 задачи, которую хотите проверить. Этот идентификатор можно получить из ответа, когда создаёте задачу или перечисляете задачи. Ответ включает текущий stateпоказатель задачи , который может быть одним из : queued, in_progress, completed``failed``idle``waiting_for_user``timed_outили .cancelled

Использование API issues

Примечание.

Эта функция уже присутствует Публичный предварительный просмотр и может измениться.

Вы можете назначать проблемы либо Copilot на использование GraphQL API, либо REST API. Оба API поддерживают опциональный ввод назначения агента для настройки задачи:

Параметр GraphQLПараметр RESTDescription
targetRepositoryIdtarget_repoРепозиторий, где Copilot будет работать
baseRefbase_branchВетвь, от которой Copilot будет разветвляться
customInstructionscustom_instructionsДополнительные инструкции для Copilot
customAgentcustom_agentA Пользовательский агент для выполнения задачи
modelmodelМодель для Copilot использования

Использование API GraphQL

Примечание.

Вы должны включить GraphQL-Features заголовок со значениями issues_copilot_assignment_api_support и coding_agent_model_selection.

Вы можете использовать следующие мутации GraphQL для присвоения проблем :Copilot

Создание и назначение новой проблемы

  1. Убедитесь, что вы аутентифицируете API с помощью пользовательского токена, например, personal access token или GitHub App токена пользователя-сервера.

    Примечание.

    Если используется , fine-grained personal access tokenдля назначения Copilot задачи нужны следующие разрешения:

    • Read access к метаданным
    • Read and Write access к действиям, содержимому, проблемам и pull requests

    Если использовать personal access token (classic), ему нужен repo прицел для назначения Copilot задачи.

  2. Проверьте, что Copilot облачный агент включено в репозитории, проверив, включает ли репозиторий suggestedActors в API GraphQL 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 репозитория, в который вы хотите создать проблему, заменив octo-org его владельцем и octo-repo именем репозитория.

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

  5. Создайте проблему с мутацией createIssue . Замените REPOSITORY_ID идентификатор, возвращенный на предыдущем шаге, и BOT_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. Убедитесь, что вы аутентифицируете API с помощью пользовательского токена, например, personal access token или GitHub App токена пользователя-сервера.

  2. Проверьте, что Copilot облачный агент включено в репозитории, проверив, включает ли репозиторий suggestedActors в API GraphQL 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. Получите глобальный идентификатор GraphQL нужного выпуска Copilot, замените monalisa его владельцем репозитория, octocat именем и 9000 номером выпуска.

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

  4. Назначите существующую проблему Copilot на использование мутации replaceActorsForAssignable . Замените ISSUE_ID на ID, вернувшийся с предыдущего шага, BOT_ID на ID, возвращённый с предыдущего шага, и REPOSITORY_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": ""
  }
}'

Дополнительные материалы