Uso de Copilot agente en la nube a través de la API

Puede iniciar y administrar agente en la nube de Copilot tareas mediante programación mediante la API REST.

¿Quién puede utilizar esta característica?

agente en la nube de Copilot está disponible para todos los planes Copilot de pago.

El agente está disponible en todos los repositorios almacenados en GitHub, excepto los repositorios propiedad de cuentas de usuario administradas y donde se ha deshabilitado explícitamente.
Sign up for Copilot

En este artículo

Puede usar la API de tareas del agente para integrar agente de nube en tus propias herramientas y flujos de trabajo. Por ejemplo, puede iniciar una nueva tarea, enumerar las tareas existentes o comprobar el estado de una tarea.

Además, puede usar las API REST y GraphQL de incidencias para asignar las incidencias a Copilot.

Uso de la API de tareas del agente

Nota:

La API de tareas del agente está en versión preliminar pública y está sujeta a cambios.

Autenticación

La API de tareas del agente solo admite tokens de usuario a servidor. Puede autenticarse mediante un personal access tokentoken , un OAuth app token o un GitHub App token de usuario a servidor.

No se admiten tokens de servidor a servidor, como GitHub App tokens de acceso de instalación.

Inicio de una tarea mediante la API

Para iniciar una nueva agente de nube tarea, envíe una POST solicitud a /agents/repos/{owner}/{repo}/tasks. El único parámetro necesario es prompt, que es la solicitud del 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"
  }'

Reemplace los valores de los marcadores de posición siguientes:

  •           `YOUR-TOKEN`: un token personal access token o GitHub App de usuario a servidor.
  • OWNER: el propietario de la cuenta del repositorio.
  • REPO: nombre del repositorio.

También puede incluir los siguientes parámetros opcionales en el cuerpo de la solicitud:

  •           `base_ref`: la rama base de la nueva rama y la solicitud de incorporación de cambios.
  • model: modelo de IA que se va a usar para la tarea. Si se omite, se usa selección automática de modelos. Para obtener más información sobre los modelos admitidos, consulte Puntos de conexión de api REST para tareas del agente.
  • create_pull_request: un valor booleano que determina si crear un pull request para la tarea.

Enumeración de tareas

Puede enumerar las tareas de un repositorio específico o de todos los repositorios a los que tiene acceso.

Para enumerar las tareas de un repositorio 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 enumerar las tareas en todos los repositorios:

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

Comprobación del estado de una tarea

Para comprobar el estado de una tarea específica, envíe una GET solicitud con el identificador de tarea:

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

Reemplace TASK-ID por el identificador de la tarea que desea comprobar. Puede obtener este identificador de la respuesta al crear una tarea o enumerar tareas. La respuesta incluye el estado actual state de la tarea, que puede ser uno de los siguientes: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out o cancelled.

Uso de la API de incidencias

Nota:

Esta característica está en versión preliminar pública y está sujeta a cambios.

Puede asignar problemas al Copilot usando la API GraphQL o la API REST. Ambas API admiten una entrada opcional de asignación de agente para personalizar la tarea:

Parámetro GraphQLParámetro RESTDescription
targetRepositoryIdtarget_repoRepositorio en el que Copilot funcionará
baseRefbase_branchLa rama en la que Copilot creará una nueva rama
customInstructionscustom_instructionsInstrucciones adicionales para Copilot
customAgentcustom_agentEl agente personalizado que se vaya a usar para la tarea
modelmodelEl modelo de Copilot que se vaya a usar

Utilizar la API de GraphQL

Nota:

Debe incluir el GraphQL-Features encabezado con los valores issues_copilot_assignment_api_support y coding_agent_model_selection.

Puede usar las siguientes mutaciones de GraphQL para asignar problemas a Copilot:

Creación y asignación de una nueva propuesta

  1. Asegúrese de autenticarse con la API mediante un token de usuario, por ejemplo, un personal access token token de usuario a servidor o un GitHub App token de usuario a servidor.

    Nota:

    Si usa fine-grained personal access token, necesita los siguientes permisos para asignar Copilot a un problema.

    • Acceso de lectura a los metadatos
    • Acceso de lectura y escritura a acciones, contenidos, incidencias y solicitudes de extracción

    Si se va a usar un personal access token (classic), necesita utilizar el permiso repo para asignar Copilot a una incidencia.

  2. Compruebe que agente en la nube de Copilot está habilitado en el repositorio comprobando si el repositorio de suggestedActors GraphQL API incluye Copilot. Reemplaza octo-org por el propietario del repositorio y octo-repo por el nombre del repositorio.

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

    Si agente en la nube de Copilot está habilitado para el usuario y en el repositorio, el primer nodo devuelto de la consulta tendrá el login valor copilot-swe-agent.

  3. Anota el valor id de este inicio de sesión.

  4. Captura el identificador global de GraphQL del repositorio en el que deseas crear la propuesta, reemplaza octo-org por el propietario del repositorio y octo-repo por el nombre del repositorio.

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

  5. Cree la propuesta con la mutación createIssue. Reemplaza REPOSITORY_ID por el id. devuelto del paso anterior y BOT_ID por el id. devuelto por el paso anterior a ese. Opcionalmente, puede incluir la agentAssignment entrada para personalizar la tarea.

    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'

Asignación de una propuesta existente

  1. Asegúrese de autenticarse con la API mediante un token de usuario, por ejemplo, un personal access token token de usuario a servidor o un GitHub App token de usuario a servidor.

  2. Compruebe que agente en la nube de Copilot está habilitado en el repositorio comprobando si el repositorio de suggestedActors GraphQL API incluye Copilot. Reemplaza octo-org por el propietario del repositorio y octo-repo por el nombre del repositorio.

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

        ... on Bot {
          id
        }

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

    Si agente en la nube de Copilot está habilitado para el usuario y en el repositorio, el primer nodo devuelto de la consulta tendrá el login valor copilot-swe-agent.

  3. Capture el identificador global de GraphQL del problema que desea asignar a Copilot, reemplazando monalisa por el propietario del repositorio, octocat por el nombre y 9000 por el número de problema.

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

  4. Asigne el problema existente a Copilot utilizando la mutación replaceActorsForAssignable. Reemplace ISSUE_ID por el identificador devuelto del paso anterior, BOT_ID por el identificador devuelto del paso anterior y REPOSITORY_ID por el identificador del repositorio. Opcionalmente, puede incluir la agentAssignment entrada para personalizar la tarea.

    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, puede usar la updateIssue mutación para actualizar un problema existente y asignarlo a Copilot. Reemplace ISSUE_ID por el identificador de problema y BOT_ID por el identificador del 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. También puede usar la instrucción de mutación addAssigneesToAssignable para añadir Copilot a una incidencia existente, junto con los usuarios que ya la tienen asignada. Reemplace ISSUE_ID por el identificador de problema y BOT_ID por el identificador del 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'

Uso de la API REST

Puede usar los siguientes puntos de conexión de la API REST para asignar problemas a Copilot:

Añadir asignados a un problema 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": ""
  }
}'

Creación de un 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": ""
  }
}'

Actualización de un 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": ""
  }
}'

Lectura adicional