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

REST API を使用して、 Copilot cloud agent タスクをプログラムで開始および管理できます。

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

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

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

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

### 認証

エージェント タスク API では、ユーザーからサーバーへのトークンのみがサポートされます。
personal access token、OAuth app トークン、またはGitHub Appユーザーからサーバーへのトークンを使用して認証できます。

GitHub Appインストール アクセス トークンなどのサーバー間トークンはサポートされていません。

### API を使用してタスクを開始する

新しいcloud agent タスクを開始するには、`POST`に`/agents/repos/{owner}/{repo}/tasks`要求を送信します。 必須のパラメーターは `prompt` のみです。これはエージェントのプロンプトです。

```shell copy
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 モデル。 省略した場合、auto model selection が使われます。 サポートされているモデルの詳細については、 [AUTOTITLE を](/ja/rest/agent-tasks/agent-tasks)参照してください。
* `create_pull_request`: タスクのプル要求を作成するかどうかを決定するブール値。

### タスクの一覧表示

特定のリポジトリまたはアクセス権を持つすべてのリポジトリのタスクを一覧表示できます。

特定のリポジトリのタスクを一覧表示するには:

```shell copy
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 copy
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 copy
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 の使用

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

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

| GraphQL パラメーター       | REST パラメーター           | Description            |
| -------------------- | --------------------- | ---------------------- |
| `targetRepositoryId` | `target_repo`         |                        |
| Copilotが機能するリポジトリ    |                       |                        |
| `baseRef`            | `base_branch`         |                        |
| Copilotが分岐元となるブランチ   |                       |                        |
| `customInstructions` | `custom_instructions` |                        |
| Copilot に関する追加の手順    |                       |                        |
| `customAgent`        | `custom_agent`        | タスクで使用する custom agent。 |
| `model`              | `model`               | 使用する Copilot のモデル      |

### GraphQL API を使用する

> \[!NOTE]
> `GraphQL-Features`ヘッダーには、`issues_copilot_assignment_api_support`と`coding_agent_model_selection`の値を含める必要があります。

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

* [`updateIssue`](/ja/graphql/reference/issues#mutation-updateissue)
* [`createIssue`](/ja/graphql/reference/issues#mutation-createissue)
* [`addAssigneesToAssignable`](/ja/graphql/reference/issues#mutation-addassigneestoassignable)
* [`replaceActorsForAssignable`](/ja/graphql/reference/issues#mutation-replaceactorsforassignable)

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

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

   > \[!NOTE]
   > fine-grained personal access tokenを使用する場合、問題にCopilotを割り当てるには、次のアクセス許可が必要です。
   >
   > * メタデータへの読み取りアクセス
   > * アクション、コンテンツ、課題、プルリクエストへのアクセスの読み取りおよび書き込み
   >
   > personal access token (classic)を使用する場合は、問題に`repo`を割り当てるためにCopilotスコープが必要です。

2. GraphQL API のリポジトリのCopilot cloud agentに`suggestedActors`が含まれているかどうかを確認して、リポジトリでCopilotが有効になっていることを確認します。
   `octo-org` をリポジトリ所有者に置き換え、`octo-repo` をリポジトリ名に置き換えます。

   ```graphql copy
   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 cloud agent が有効になっている場合、クエリから返された最初のノードには `login` 値 `copilot-swe-agent`。

3. このログインの `id` の値を記録しておきます。

4. Issue を作成するリポジトリの GraphQL グローバル ID をフェッチし、`octo-org` をリポジトリ所有者に置き換え、`octo-repo` をリポジトリ名に置き換えます。

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

5. `createIssue` ミューテーションを使って issue を作成します。
   `REPOSITORY_ID` を前のステップで返された ID に置き換え、`BOT_ID` をその前のステップで返された ID に置き換えます。 必要に応じて、 `agentAssignment` 入力を含め、タスクをカスタマイズできます。

   ```shell copy
   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 cloud agentに`suggestedActors`が含まれているかどうかを確認して、リポジトリでCopilotが有効になっていることを確認します。
   `octo-org` をリポジトリ所有者に置き換え、`octo-repo` をリポジトリ名に置き換えます。

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

           ... on Bot {
             id
           }

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

   ユーザーとリポジトリで Copilot cloud agent が有効になっている場合、クエリから返された最初のノードには `login` 値 `copilot-swe-agent`。

3. Copilotに割り当てる問題の GraphQL グローバル ID を取得し、`monalisa`をリポジトリの所有者に置き換え、`octocat`名前に、`9000`を問題番号に置き換えます。

   ```graphql copy
   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 copy
   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 copy
   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 copy
   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に問題を割り当てることができます。

* [課題に担当者を追加する](/ja/rest/issues/assignees#add-assignees-to-an-issue)
* [問題を作成する](/ja/rest/issues/issues#create-an-issue)
* [問題を更新する](/ja/rest/issues/issues#update-an-issue)

#### 既存の問題への担当者の追加

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

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

* [エージェント タスクの REST API エンドポイント](/ja/rest/agent-tasks/agent-tasks)
* [クラウド エージェントGitHub Copilotについて](/ja/copilot/concepts/agents/cloud-agent/about-cloud-agent)
* [GitHub Copilot セッションの開始](/ja/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions)