# Using Copilot cloud agent via the API

> You can start and manage Copilot cloud agent tasks programmatically using the REST API.

- 网址：https://funcoding.ai/agents/github-copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-via-the-api/
- 来源：GitHub Copilot 官方文档原文（英文），CC-BY-4.0 许可，同步于 2026-10-11
- 官方原文：https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-via-the-api

---
You can use the agent tasks API to integrate cloud agent into your own tools and workflows. For example, you can start a new task, list existing tasks, or check the status of a task.

In addition, you can use the REST and GraphQL APIs for issues to assign issues to Copilot.

## Using the agent tasks API

<div class="callout callout-note">

The agent tasks API is in public preview and subject to change.

</div>

### Authentication

The agent tasks API only supports user-to-server tokens. You can authenticate using a personal access token, a OAuth app token or a GitHub App user-to-server token.

Server-to-server tokens, such as GitHub App installation access tokens, are not supported.

### Starting a task via the API

To start a new cloud agent task, send a `POST` request to `/agents/repos/{owner}/{repo}/tasks`. The only required parameter is `prompt`, which is the prompt for the agent.

```shell copy
curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -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"
  }'
```

Replace the following placeholder values:

* `YOUR-TOKEN`: A personal access token or GitHub App user-to-server token.
* `OWNER`: The account owner of the repository.
* `REPO`: The name of the repository.

You can also include the following optional parameters in the request body:

* `base_ref`: The base branch for the new branch and pull request.
* `model`: The AI model to use for the task. If omitted, auto model selection is used. For more information about supported models, see [AUTOTITLE](https://docs.github.com/rest/agent-tasks/agent-tasks).
* `create_pull_request`: A boolean that determines whether to create a pull request for the task.

### Listing tasks

You can list tasks for a specific repository or across all repositories you have access to.

To list tasks for a specific repository:

```shell copy
curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks
```

To list your tasks across all repositories:

```shell copy
curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/tasks
```

### Checking the status of a task

To check the status of a specific task, send a `GET` request with the task ID:

```shell copy
curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks/TASK-ID
```

Replace `TASK-ID` with the ID of the task you want to check. You can get this ID from the response when you create a task or list tasks. The response includes the task's current `state`, which can be one of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, or `cancelled`.

## Using the issues API

<div class="callout callout-note">

This feature is in public preview and subject to change.

</div>

You can assign issues to Copilot using either the GraphQL API or the REST API. Both APIs support an optional Agent Assignment input to customize the task:

| GraphQL parameter | REST parameter | Description |
| --- | --- | --- |
| `targetRepositoryId` | `target_repo` | The repository where Copilot will work |
| `baseRef` | `base_branch` | The branch that Copilot will branch from |
| `customInstructions` | `custom_instructions` | Additional instructions for Copilot |
| `customAgent` | `custom_agent` | A custom agent to use for the task |
| `model` | `model` | The model for Copilot to use |

### Using the GraphQL API

<div class="callout callout-note">

You must include the `GraphQL-Features` header with the values `issues_copilot_assignment_api_support` and `coding_agent_model_selection`.

</div>

You can use the following GraphQL mutations to assign issues to Copilot:

* [`updateIssue`](https://docs.github.com/graphql/reference/issues#mutation-updateissue)
* [`createIssue`](https://docs.github.com/graphql/reference/issues#mutation-createissue)
* [`addAssigneesToAssignable`](https://docs.github.com/graphql/reference/issues#mutation-addassigneestoassignable)
* [`replaceActorsForAssignable`](https://docs.github.com/graphql/reference/issues#mutation-replaceactorsforassignable)

#### Creating and assigning a new issue

1. Make sure you're authenticating with the API using a user token, for example a personal access token or a GitHub App user-to-server token.

<div class="callout callout-note">

If using a fine-grained personal access token, it needs the following permissions to assign Copilot to an issue:
* Read access to metadata
* Read and write access to actions, contents, issues and pull requests

If using a personal access token (classic), it needs the `repo` scope to assign Copilot to an issue.

</div>

1. Verify that Copilot cloud agent is enabled in the repository by checking if the repository's `suggestedActors` in the GraphQL API includes Copilot. Replace `octo-org` with the repository owner, and `octo-repo` with the repository name.

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

    If Copilot cloud agent is enabled for the user and in the repository, the first node returned from the query will have the `login` value `copilot-swe-agent`.

1. Make a note of the `id` value of this login.

1. Fetch the GraphQL global ID of the repository you want to create the issue in, replacing `octo-org` with the repository owner, and `octo-repo` with the repository name.

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

1. Create the issue with the `createIssue` mutation. Replace `REPOSITORY_ID` with the ID returned from the previous step, and `BOT_ID` with the ID returned from the step before that. You can optionally include the `agentAssignment` input to customize the task.

    ```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'
    ```

#### Assigning an existing issue

1. Make sure you're authenticating with the API using a user token, for example a personal access token or a GitHub App user-to-server token.
1. Verify that Copilot cloud agent is enabled in the repository by checking if the repository's `suggestedActors` in the GraphQL API includes Copilot. Replace `octo-org` with the repository owner, and `octo-repo` with the repository name.

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

            ... on Bot {
              id
            }

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

    If Copilot cloud agent is enabled for the user and in the repository, the first node returned from the query will have the `login` value `copilot-swe-agent`.

1. Fetch the GraphQL global ID of the issue you want to assign to Copilot, replacing `monalisa` with the repository owner, `octocat` with the name and `9000` with the issue number.

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

1. Assign the existing issue to Copilot using the `replaceActorsForAssignable` mutation. Replace `ISSUE_ID` with the ID returned from the previous step, `BOT_ID` with the ID returned from the step before that, and `REPOSITORY_ID` with the repository ID. You can optionally include the `agentAssignment` input to customize the task.

    ```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'
    ```

1. Alternatively, you can use the `updateIssue` mutation to update an existing issue and assign it to Copilot. Replace `ISSUE_ID` with the issue ID and `BOT_ID` with the bot 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'
    ```

1. You can also use the `addAssigneesToAssignable` mutation to add Copilot to an existing issue while keeping other assignees. Replace `ISSUE_ID` with the issue ID and `BOT_ID` with the bot 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'
    ```

### Using the REST API

You can use the following REST API endpoints to assign issues to Copilot:

* [Add assignees to an issue](https://docs.github.com/rest/issues/assignees#add-assignees-to-an-issue)
* [Create an issue](https://docs.github.com/rest/issues/issues#create-an-issue)
* [Update an issue](https://docs.github.com/rest/issues/issues#update-an-issue)

#### Adding assignees to an existing 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": ""
  }
}'
```

#### Creating a new 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 \
  --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": ""
  }
}'
```

#### Updating an existing issue

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

## Further reading

* [AUTOTITLE](https://docs.github.com/rest/agent-tasks/agent-tasks)
* [AUTOTITLE](https://funcoding.ai/agents/github-copilot/concepts/copilot-surfaces/copilot-on-github/)
* [AUTOTITLE](https://funcoding.ai/agents/github-copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions/)