Utilisation de Copilot agent cloud via l’API

Vous pouvez démarrer et gérer des Agent cloud Copilot tâches par programmation à l’aide de l’API REST.

Qui peut utiliser cette fonctionnalité ?

Agent cloud Copilot est disponible pour tous les plans payants Copilot .

L’agent est disponible dans tous les référentiels stockés sur GitHub, à l’exception des référentiels détenus par comptes d’utilisateur managés et où il a été désactivé explicitement.
Sign up for Copilot

Dans cet article

Vous pouvez utiliser l’API tâches de l’agent pour l’intégrer agent de cloud à vos propres outils et flux de travail. Par exemple, vous pouvez démarrer une nouvelle tâche, répertorier les tâches existantes ou vérifier l’état d’une tâche.

En outre, vous pouvez utiliser les API REST et GraphQL pour les tickets afin d’attribuer des tickets à Copilot.

Utilisation de l’API tâches de l’agent

Remarque

L'API des tâches de l'agent est en développement préversion publique et susceptible d'être modifiée.

Authentification

L’API tâches de l’agent prend uniquement en charge les jetons utilisateur-à-serveur. Vous pouvez vous authentifier à l’aide d’un personal access token, d’un jeton OAuth app ou d’un jeton utilisateur à serveur GitHub App.

Les jetons serveur à serveur, tels que GitHub App les jetons d’accès d’installation, ne sont pas pris en charge.

Démarrage d’une tâche via l’API

Pour démarrer une nouvelle agent de cloud tâche, envoyez une POST demande à /agents/repos/{owner}/{repo}/tasks. Le seul paramètre requis est prompt, qui est l’invite de l’agent.

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

Remplacez les valeurs d’espace réservé suivantes :

  • YOUR-TOKEN: Un jeton utilisateur-à-serveur personal access token ou GitHub App.
  • OWNER: Le propriétaire du compte du dépôt.
  • REPO: nom du référentiel.

Vous pouvez également inclure les paramètres facultatifs suivants dans le corps de la requête :

  •           `base_ref`: branche de base pour la nouvelle branche et la pull request.
  • model: modèle IA à utiliser pour la tâche. Si elle est omise, sélection automatique de modèle est utilisé. Pour plus d’informations sur les modèles pris en charge, consultez Points de terminaison d’API REST pour les tâches de l’agent.
  • create_pull_request: Un booléen indiquant s'il convient de créer un pull request pour la tâche.

Liste des tâches

Vous pouvez répertorier les tâches d’un référentiel spécifique ou de tous les référentiels auxquels vous avez accès.

Pour répertorier les tâches d’un référentiel spécifique :

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

Pour répertorier vos tâches dans tous les référentiels :

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

Vérification de l’état d’une tâche

Pour vérifier l’état d’une tâche spécifique, envoyez une GET demande avec l’ID de tâche :

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

Remplacez TASK-ID par l’ID de la tâche que vous souhaitez vérifier. Vous pouvez obtenir cet ID à partir de la réponse lorsque vous créez une tâche ou une liste de tâches. La réponse inclut l’actuel statede la tâche, qui peut être l’un des suivants : queued, , in_progress``completed, failed, idle, , waiting_for_user, , timed_out, ou cancelled.

Utilisation de l’API des problèmes

Remarque

Cette fonctionnalité est en cours de développement préversion publique et est susceptible de changer.

Vous pouvez affecter des problèmes à Copilot à l’aide de l’API GraphQL ou de l’API REST. Les deux API prennent en charge une entrée d’affectation d’agent facultative pour personnaliser la tâche :

Paramètre GraphQLParamètre RESTDescription
targetRepositoryIdtarget_repoLe référentiel où travaillera Copilot
baseRefbase_branchBranche à partir de laquelle Copilot se sépare
customInstructionscustom_instructionsInstructions supplémentaires pour Copilot
customAgentcustom_agentUn assistant personnalisé à utiliser pour la tâche
modelmodelModèle à Copilot utiliser

Utilisation de l’API GraphQL

Remarque

Vous devez inclure l’en-tête GraphQL-Features avec les valeurs issues_copilot_assignment_api_support et coding_agent_model_selection.

Vous pouvez utiliser les mutations GraphQL suivantes pour affecter des problèmes à Copilot:

Création et affectation d’un problème

  1. Vérifiez que vous vous authentifiez avec l’API à l’aide d’un jeton utilisateur, par exemple un personal access tokenGitHub App jeton utilisateur à serveur.

    Remarque

    Si vous utilisez un fine-grained personal access token, les autorisations suivantes sont nécessaires pour attribuer Copilot à un problème :

    • Accès en lecture aux métadonnées
    • Accès en lecture et en écriture aux actions, contenus, problèmes et demandes de tirage

    Si vous utilisez un personal access token (classic), il nécessite l'étendue repo pour attribuer Copilot à un problème.

  2. Vérifiez que Agent cloud Copilot soit activé dans le référentiel en vérifiant si l'API GraphQL suggestedActors inclut Copilot. Remplacez octo-org par le propriétaire du référentiel, et octo-repo par le nom du référentiel.

    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 Agent cloud Copilot est activé pour l’utilisateur et dans le référentiel, le premier nœud retourné par la requête aura la valeur login``copilot-swe-agent.

  3. Notez la valeur id de cette connexion.

  4. Récupérez l’ID global GraphQL du référentiel dans lequel vous souhaitez créer le ticket, en remplaçant octo-org par le propriétaire du référentiel et octo-repo par le nom du référentiel.

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

  5. Créez le problème avec la mutation createIssue. Remplacez REPOSITORY_ID par l’id renvoyé à l’étape précédente, et BOT_ID par l’id renvoyé à l’étape précédente. Vous pouvez éventuellement inclure l’entrée agentAssignment pour personnaliser la tâche.

    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'

Affectation d’un problème existant

  1. Vérifiez que vous vous authentifiez avec l’API à l’aide d’un jeton utilisateur, par exemple un personal access tokenGitHub App jeton utilisateur à serveur.

  2. Vérifiez que Agent cloud Copilot soit activé dans le référentiel en vérifiant si l'API GraphQL suggestedActors inclut Copilot. Remplacez octo-org par le propriétaire du référentiel, et octo-repo par le nom du référentiel.

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

        ... on Bot {
          id
        }

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

    Si Agent cloud Copilot est activé pour l’utilisateur et dans le référentiel, le premier nœud retourné par la requête aura la valeur login``copilot-swe-agent.

  3. Récupérez l’ID global GraphQL du problème auquel Copilotvous souhaitez affecter , en remplaçant monalisa par le propriétaire du référentiel, octocat par le nom et 9000 par le numéro de problème.

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

  4. Affectez le problème existant à Copilot en utilisant la replaceActorsForAssignable mutation. Remplacez ISSUE_ID par l’ID retourné à l’étape précédente, BOT_ID par l’ID retourné par l’étape précédente et REPOSITORY_ID par l’ID de référentiel. Vous pouvez éventuellement inclure l’entrée agentAssignment pour personnaliser la tâche.

    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. Vous pouvez également utiliser la updateIssue mutation pour mettre à jour un problème existant et l’affecter à Copilot. Remplacez ISSUE_ID par l’ID de problème et BOT_ID par l’ID du 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. Vous pouvez également utiliser la addAssigneesToAssignable mutation pour ajouter Copilot à un problème existant tout en gardant d'autres attributions. Remplacez ISSUE_ID par l’ID de problème et BOT_ID par l’ID du 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'

Utilisation de l’API REST

Vous pouvez utiliser les points de terminaison d’API REST suivants pour affecter des problèmes à Copilot:

Ajouter des assignés à un problème existant

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

Création d’un problème

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

Mise à jour d’un problème existant

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

Lectures complémentaires