API を使用してCopilotクラウドエージェントを利用する

REST API を使用して、 Copilot クラウドエージェント タスクをプログラムで開始および管理できます。

この機能を使用できるユーザーについて

Copilot クラウドエージェント は、すべての有料 Copilot プランで使用できます。

エージェントは、GitHubが所有し、明示的に無効にされているリポジトリを除き、マネージド ユーザー アカウントに格納されているすべてのリポジトリで使用できます。
Sign up for Copilot

この記事で

エージェント タスク API を使用して、 クラウド エージェント を独自のツールとワークフローに統合できます。 たとえば、新しいタスクを開始したり、既存のタスクを一覧表示したり、タスクの状態を確認したりできます。

さらに、REST API と GraphQL API を使用して問題を Copilotに割り当てることができます。

エージェント タスク API の使用

メモ

エージェント タスク API は パブリック プレビュー であり、変更される可能性があります。

認証

エージェント タスク API では、ユーザーからサーバーへのトークンのみがサポートされます。 personal access token、OAuth app トークン、またはGitHub 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: personal access token または GitHub App ユーザーからサーバーへのトークン。
  • OWNER: リポジトリのアカウント所有者。
  • REPO: リポジトリの名前。

要求本文には、次の省略可能なパラメーターを含めることもできます。

  •           `base_ref`: 新しい分岐とプル要求のベース分岐。
  • model: タスクに使用する AI モデル。 省略した場合、自動モデルの選択 が使われます。 サポートされているモデルの詳細については、 AUTOTITLE を参照してください。
  • create_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

タスクの状態の確認

特定のタスクの状態を確認するには、タスク ID を使用して 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 に置き換えます。 この ID は、タスクまたはリスト タスクを作成するときに応答から取得できます。 応答には、タスクの現在の state ( queued、 in_progress、 completed、 failed、 idle、 waiting_for_user、 timed_out、または cancelledのいずれか) が含まれます。

issues API の使用

メモ

この機能は パブリック プレビュー であり、変更される可能性があります。

GraphQL API または REST API を使用して、 Copilot に問題を割り当てることができます。 どちらの API でも、タスクをカスタマイズするためのオプションのエージェント割り当て入力がサポートされています。

GraphQL パラメーターREST パラメーターDescription
targetRepositoryIdtarget_repo
Copilotが機能するリポジトリ
baseRefbase_branch
Copilotが分岐元となるブランチ
customInstructionscustom_instructions
Copilot に関する追加の手順
customAgentcustom_agentタスクで使用する カスタム エージェント。
modelmodel使用する Copilot のモデル

GraphQL API を使用する

メモ

GraphQL-Featuresヘッダーには、issues_copilot_assignment_api_supportとcoding_agent_model_selectionの値を含める必要があります。

次の GraphQL の変更を使用して、 Copilotに問題を割り当てることができます。

新しい issue の作成と割り当て

  1. personal access tokenやGitHub Appユーザーからサーバーへのトークンなど、ユーザー トークンを使用して API を使用して認証していることを確認します。

    メモ

    fine-grained personal access tokenを使用する場合、問題にCopilotを割り当てるには、次のアクセス許可が必要です。

    • メタデータへの読み取りアクセス
    • アクション、コンテンツ、課題、プルリクエストへのアクセスの読み取りおよび書き込み

    personal access token (classic)を使用する場合は、問題にrepoを割り当てるためにCopilotスコープが必要です。

  2. GraphQL API のリポジトリのCopilot クラウドエージェントにsuggestedActorsが含まれているかどうかを確認して、リポジトリで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. Issue を作成するリポジトリの GraphQL グローバル ID をフェッチし、octo-org をリポジトリ所有者に置き換え、octo-repo をリポジトリ名に置き換えます。

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

  5. createIssue ミューテーションを使って issue を作成します。 REPOSITORY_ID を前のステップで返された ID に置き換え、BOT_ID をその前のステップで返された 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'

既存の issue

  1. personal access tokenやGitHub Appユーザーからサーバーへのトークンなど、ユーザー トークンを使用して API を使用して認証していることを確認します。

  2. GraphQL API のリポジトリのCopilot クラウドエージェントにsuggestedActorsが含まれているかどうかを確認して、リポジトリで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. Copilotに割り当てる問題の GraphQL グローバル ID を取得し、monalisaをリポジトリの所有者に置き換え、octocat名前に、9000を問題番号に置き換えます。

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

  4. Copilotの変更を使用して、既存の問題をreplaceActorsForAssignableに割り当てます。 ISSUE_IDを前の手順から返された ID に置き換え、BOT_IDその前の手順から返された 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": ""
  }
}'

詳細については、次を参照してください。