Usando Copilot agente de nuvem por meio da API

Você pode iniciar e gerenciar agente de nuvem Copilot tarefas programaticamente usando a API REST.

Quem pode usar esse recurso?

agente de nuvem Copilot está disponível para todos os planos Copilot pagos.

O agente está disponível em todos os repositórios armazenados em GitHub, exceto nos repositórios de propriedade de contas de usuário gerenciadas e onde foi explicitamente desativado.
Sign up for Copilot

Neste artigo

Você pode usar a API de tarefas do agente para integrar agente de nuvem às suas próprias ferramentas e fluxos de trabalho. Por exemplo, você pode iniciar uma nova tarefa, listar tarefas existentes ou verificar o status de uma tarefa.

Além disso, você pode usar as APIs REST e GraphQL para problemas para atribuir problemas a Copilot.

Usando a API de tarefas do agente

Observação

A API de tarefas do agente está dentro prévia pública e sujeita a alterações.

Autenticação

A API de tarefas do agente dá suporte apenas a tokens de usuário para servidor. Você pode autenticar usando um personal access tokentoken, um OAuth app token ou um GitHub App token de usuário para servidor.

Não há suporte para tokens entre servidores, como tokens de acesso à instalação GitHub App.

Iniciando uma tarefa por meio da API

Para iniciar uma nova agente de nuvem tarefa, envie uma solicitação POST para /agents/repos/{owner}/{repo}/tasks. O único parâmetro necessário é prompt, que é o prompt para o agente.

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

Substitua os seguintes valores de espaço reservado:

  •           `YOUR-TOKEN`: um token de usuário para servidor personal access token ou GitHub App.
  • OWNER: o proprietário da conta associada ao repositório.
  • REPO: o nome do repositório.

Você também pode incluir os seguintes parâmetros opcionais no corpo da solicitação:

  •           `base_ref`: a ramificação de base da nova ramificação e pull request.
  • model: o modelo de IA a ser usado para a tarefa. Se omitido, Seleção de modelo automática será usado. Para obter mais informações sobre modelos com suporte, consulte Endpoints da API REST para tarefas de agente.
  • create_pull_request: um booliano que determina se uma solicitação de pull deve ser criada para a tarefa.

Listar tarefas

Você pode listar tarefas para um repositório específico ou em todos os repositórios aos quais você tem acesso.

Para listar tarefas para um repositório específico:

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

Para listar suas tarefas em todos os repositórios:

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

Verificando o status de uma tarefa

Para verificar o status de uma tarefa específica, envie uma GET solicitação com a ID da tarefa:

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

Substitua TASK-ID pela ID da tarefa que você deseja verificar. Você pode obter essa ID da resposta ao criar uma tarefa ou listar tarefas. A resposta inclui a atual stateda tarefa, que pode ser uma das seguintes: queued, , in_progress, completed, failed, idle, , waiting_for_user, timed_outou cancelled.

Usar a API de problemas

Observação

Esse recurso está dentro prévia pública e sujeito a alterações.

Você pode atribuir problemas ao Copilot usando a API GraphQL ou a API REST. Ambas as APIs dão suporte a uma entrada opcional de Atribuição de Agente para personalizar a tarefa:

Parâmetro GraphQLParâmetro RESTDescription
targetRepositoryIdtarget_repoO repositório onde Copilot funcionará
baseRefbase_branchA ramificação da qual Copilot irá se ramificar
customInstructionscustom_instructionsInstruções adicionais para Copilot
customAgentcustom_agentUm agente personalizado a ser usado para a tarefa
modelmodelO modelo para Copilot para usar

Usando a API GraphQL

Observação

Você deve incluir o GraphQL-Features cabeçalho com os valores issues_copilot_assignment_api_support e coding_agent_model_selection.

Você pode usar as seguintes mutações do GraphQL para atribuir problemas a Copilot:

Criar e atribuir um novo issue

  1. Verifique se você está autenticando com a API usando um token de usuário, por exemplo, um personal access token ou um GitHub App token de usuário para servidor.

    Observação

    Se estiver usando um fine-grained personal access token, ele precisará das seguintes permissões para atribuir Copilot a um problema:

    • Acesso de leitura a metadados
    • Acesso de leitura e gravação a ações, conteúdo, problemas e pull requests

    Se estiver usando um personal access token (classic), ele precisará do repo escopo para atribuir Copilot a um problema.

  2. Verifique se agente de nuvem Copilot está habilitado no repositório verificando se o suggestedActors do repositório na API GraphQL inclui Copilot. Substitua octo-org pelo proprietário do repositório e octo-repo pelo nome do repositório.

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

    Se agente de nuvem Copilot estiver habilitado para o usuário e no repositório, o primeiro nó retornado da consulta terá o login valor copilot-swe-agent.

  3. Anote o valor id desse logon.

  4. Busque a ID global do GraphQL do repositório no qual você deseja criar o issue, substituindo octo-org pelo proprietário do repositório e octo-repo pelo nome do repositório.

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

  5. Crie o issue com a mutação createIssue. Substitua REPOSITORY_ID pela ID retornada da etapa anterior e BOT_ID pela ID retornada da etapa anterior àquela. Opcionalmente, você pode incluir a agentAssignment entrada para personalizar a tarefa.

    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'

Atribuir um issue existente

  1. Verifique se você está autenticando com a API usando um token de usuário, por exemplo, um personal access token ou um GitHub App token de usuário para servidor.

  2. Verifique se agente de nuvem Copilot está habilitado no repositório verificando se o suggestedActors do repositório na API GraphQL inclui Copilot. Substitua octo-org pelo proprietário do repositório e octo-repo pelo nome do repositório.

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

        ... on Bot {
          id
        }

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

    Se agente de nuvem Copilot estiver habilitado para o usuário e no repositório, o primeiro nó retornado da consulta terá o login valor copilot-swe-agent.

  3. Busque a ID global do GraphQL do problema ao qual você deseja atribuir Copilot, substituindo monalisa pelo proprietário do repositório, octocat pelo nome e 9000 pelo número do problema.

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

  4. Atribua o problema existente a Copilot usando a mutação replaceActorsForAssignable. Substitua ISSUE_ID pela ID retornada da etapa anterior, BOT_ID pela ID retornada da etapa anterior e REPOSITORY_ID pela ID do repositório. Opcionalmente, você pode incluir a agentAssignment entrada para personalizar a tarefa.

    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. Como alternativa, você pode usar a updateIssue mutação para atualizar um problema existente e atribuí-lo a Copilot. Substitua ISSUE_ID pela ID do problema e BOT_ID pela ID do bot.

    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. Você também pode usar a addAssigneesToAssignable alteração para adicionar Copilot a um problema existente, mantendo os outros responsáveis. Substitua ISSUE_ID pela ID do problema e BOT_ID pela ID do bot.

    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'

Usando a API REST

Você pode usar os seguintes pontos de extremidade da API REST para atribuir problemas a Copilot:

Adicionando responsáveis a um problema já existente

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

Criando um novo problema

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

Atualizando um problema existente

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

Leitura adicional