Die Verwendung des Copilot-Cloud-Agents über die API

Sie können Aufgaben programmgesteuert mithilfe der REST-API starten und verwalten Copilot-Cloud-Agent .

Wer kann dieses Feature verwenden?

Copilot-Cloud-Agent ist für alle kostenpflichtigen Copilot Pläne verfügbar.

Der Agent ist in allen Repositorys verfügbar, die auf GitHub gespeichert sind, mit Ausnahme von Repositorys, die im Besitz von verwaltete Benutzerkonten sind und wo er explizit deaktiviert wurde.
Sign up for Copilot

In diesem Artikel

Sie können die Agentaufgaben-API verwenden, um Cloud-Agent in Ihre eigenen Tools und Workflows zu integrieren. Sie können z. B. eine neue Aufgabe starten, vorhandene Aufgaben auflisten oder den Status einer Aufgabe überprüfen.

Darüber hinaus können Sie die REST- und GraphQL-APIs für Probleme verwenden, um Probleme an Copilot zuzuweisen.

Verwenden der API für Agent-Aufgaben

Hinweis

Die Agentaufgaben-API befindet sich in Öffentliche Vorschau und kann geändert werden.

Authentifizierung

Die Agentaufgaben-API unterstützt nur Benutzer-zu-Server-Token. Sie können sich mit einem personal access tokenToken, einem OAuth app Token oder einem GitHub App Benutzer-zu-Server-Token authentifizieren.

Server-zu-Server-Token, wie GitHub App Installationszugriffstoken, werden nicht unterstützt.

Starten einer Aufgabe über die API

Um eine neue Cloud-Agent Aufgabe zu starten, senden Sie eine POST Anforderung an /agents/repos/{owner}/{repo}/tasks. Der einzige erforderliche Parameter ist prompt, bei dem es sich um die Aufforderung für den Agent handelt.

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

Ersetzen Sie die folgenden Platzhalterwerte:

  • YOUR-TOKEN: Ein personal access token- oder GitHub App-Benutzer-zu-Server-Token.
  • OWNER: Der Kontobesitzer des Repositorys.
  • REPO: Der Name des Repositorys.

Sie können auch die folgenden optionalen Parameter in den Anforderungstext einschließen:

  •           `base_ref`: Die Basisverzweigung für die neue Verzweigung und Pull-Anforderung.
  • model: Das KI-Modell, das für die Aufgabe verwendet werden soll. Wenn nicht angegeben, wird Automatische Modellauswahl verwendet. Weitere Informationen zu unterstützten Modellen finden Sie unter REST-API-Endpunkte für Agentaufgaben.
  • create_pull_request: Ein boolescher Wert, der bestimmt, ob eine Pullanforderung für die Aufgabe erstellt werden soll.

Auflisten von Aufgaben

Sie können Aufgaben für ein bestimmtes Repository oder für alle Repositorys auflisten, auf die Sie Zugriff haben.

So listen Sie Aufgaben für ein bestimmtes Repository auf:

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

So listen Sie Ihre Aufgaben in allen Repositorys auf:

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

Überprüfen des Status eines Vorgangs

Um den Status einer bestimmten Aufgabe zu überprüfen, senden Sie eine GET Anforderung mit der Aufgaben-ID:

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

Ersetzen Sie sie TASK-ID durch die ID der Aufgabe, die Sie überprüfen möchten. Sie können diese ID aus der Antwort abrufen, wenn Sie eine Aufgabe oder Listenaufgaben erstellen. Die Antwort enthält den aktuellen state-Vorgang, der eine von: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out oder cancelled sein kann.

Verwendung der Issues-API

Hinweis

Diese Funktion befindet sich in Öffentliche Vorschau und kann Änderungen unterliegen.

Sie können Probleme Copilot entweder mit der GraphQL-API oder der REST-API zuweisen. Beide APIs unterstützen eine optionale Agent-Zuweisungseingabe zum Anpassen der Aufgabe:

GraphQL-ParameterREST-ParameterDescription
targetRepositoryIdtarget_repoDas Repository, in dem Copilot arbeiten wird
baseRefbase_branchDer Zweig, von dem Copilot abzweigen wird
customInstructionscustom_instructionsZusätzliche Anweisungen für Copilot
customAgentcustom_agentBenutzerdefinierter Agent für die Aufgabe.
modelmodelDas Modell für Copilot zur Verwendung

Verwenden der GraphQL-API

Hinweis

Sie müssen die GraphQL-Features Kopfzeile mit den Werten issues_copilot_assignment_api_support und coding_agent_model_selection beifügen.

Sie können die folgenden GraphQL-Mutationen verwenden, um Probleme zuzuweisen Copilot:

Erstellen und Zuweisen eines neuen Issues

  1. Stellen Sie sicher, dass Sie sich mit der API mit einem Benutzertoken authentifizieren, z. B. mit einem personal access tokenGitHub App Benutzer-zu-Server-Token.

    Hinweis

    Wenn Sie ein fine-grained personal access token verwenden, benötigt es die folgenden Berechtigungen, um Copilot einem Problem zuzuweisen:

    • Lesezugriff auf Metadaten
    • Lese- und Schreibzugriff auf Aktionen, Inhalte, Probleme und Pullanforderungen

    Falls ein personal access token (classic) verwendet wird, benötigt es den repo-Bereich, um Copilot einem Problem zuzuweisen.

  2. Überprüfen Sie, ob Copilot-Cloud-Agent im Repository aktiviert ist, indem Sie prüfen, ob die GraphQL-API des Repositories suggestedActorsCopilot enthält. Ersetze octo-org durch die Person im Repositorybesitz und octo-repo durch den Repositorynamen.

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

    Wenn Copilot-Cloud-Agent für den Benutzer und im Repository aktiviert ist, weist der erste von der Abfrage zurückgegebene Knoten den login Wert copilot-swe-agentauf.

  3. Notiere den Wert id dieser Anmeldung.

  4. Rufe die globale GraphQL-ID des Repositorys ab, in dem du das Issue erstellen möchtest, ersetze octo-org durch die Person im Repositorybesitz und octo-repo durch den Repositorynamen.

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

  5. Erstelle das Issue mit der createIssue-Mutation. Ersetze REPOSITORY_ID durch die im vorherigen Schritt zurückgegebene ID und BOT_ID durch die im Schritt davor zurückgegebene ID. Optional können Sie die agentAssignment Eingabe einschließen, um die Aufgabe anzupassen.

    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'

Zuweisen eines vorhandenen Issues

  1. Stellen Sie sicher, dass Sie sich mit der API mit einem Benutzertoken authentifizieren, z. B. mit einem personal access tokenGitHub App Benutzer-zu-Server-Token.

  2. Überprüfen Sie, ob Copilot-Cloud-Agent im Repository aktiviert ist, indem Sie prüfen, ob die GraphQL-API des Repositories suggestedActorsCopilot enthält. Ersetze octo-org durch die Person im Repositorybesitz und octo-repo durch den Repositorynamen.

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

        ... on Bot {
          id
        }

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

    Wenn Copilot-Cloud-Agent für den Benutzer und im Repository aktiviert ist, weist der erste von der Abfrage zurückgegebene Knoten den login Wert copilot-swe-agentauf.

  3. Rufen Sie die globale GraphQL-ID des Issues ab, das Sie Copilot zuweisen möchten. Ersetzen Sie monalisa durch den Repositorybesitzer, octocat durch den Namen und 9000 durch die Problemnummer.

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

  4. Weisen Sie das vorhandene Problem Copilot zu mit der Mutation replaceActorsForAssignable. Ersetzen Sie ISSUE_ID durch die ID, die aus dem vorherigen Schritt zurückgegeben wurde, BOT_ID durch die ID, die vor diesem Schritt zurückgegeben wurde, und REPOSITORY_ID durch die Repository-ID. Optional können Sie die agentAssignment Eingabe einschließen, um die Aufgabe anzupassen.

    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. Alternativ können Sie die updateIssue Mutation verwenden, um ein vorhandenes Problem zu aktualisieren und es zuzuweisen Copilot. Ersetzen Sie ISSUE_ID mit der Problem-ID und BOT_ID mit der Bot-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. Sie können auch die addAssigneesToAssignable Mutation verwenden, um Copilot zu einem vorhandenen Problem hinzuzufügen, während andere Bearbeiter beibehalten werden. Ersetzen Sie ISSUE_ID mit der Problem-ID und BOT_ID mit der Bot-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'

Verwenden der REST-API

Sie können die folgenden REST-API-Endpunkte verwenden, um Probleme zuzuweisen Copilot:

Hinzufügen von Zuständigen zu einem vorhandenen Vorgang

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

Erstellen eines neuen Problems

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

Aktualisieren eines vorhandenen Problems

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

Weiterführende Lektüre