diff --git a/assets/images/help/copilot/copilot-sdk/agent-loop-architecture.png b/assets/images/help/copilot/copilot-sdk/agent-loop-architecture.png new file mode 100644 index 000000000000..ed60ea09d6d9 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/agent-loop-architecture.png differ diff --git a/assets/images/help/copilot/copilot-sdk/agent-loop-event-flow.png b/assets/images/help/copilot/copilot-sdk/agent-loop-event-flow.png new file mode 100644 index 000000000000..f20fe70ec773 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/agent-loop-event-flow.png differ diff --git a/assets/images/help/copilot/copilot-sdk/agent-loop-tool-use-loop.png b/assets/images/help/copilot/copilot-sdk/agent-loop-tool-use-loop.png new file mode 100644 index 000000000000..e22cdb278b24 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/agent-loop-tool-use-loop.png differ diff --git a/assets/images/help/copilot/copilot-sdk/bundled-cli-architecture.png b/assets/images/help/copilot/copilot-sdk/bundled-cli-architecture.png new file mode 100644 index 000000000000..20e37f37d830 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/bundled-cli-architecture.png differ diff --git a/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png b/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png index 1a838172790a..ec07e4f6c5dd 100644 Binary files a/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png and b/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png differ diff --git a/content/actions/concepts/security/github_token.md b/content/actions/concepts/security/github_token.md index 101873ecb605..71664d6301a6 100644 --- a/content/actions/concepts/security/github_token.md +++ b/content/actions/concepts/security/github_token.md @@ -29,6 +29,11 @@ The token is also available in the `github.token` context. For more information, {% data reusables.actions.actions-do-not-trigger-workflows %} +{% ifversion actions-github-token-pull-request-approval %} +> [!NOTE] +> If you need workflow runs from workflow-created pull requests to execute without requiring approval, use a {% data variables.product.prodname_github_app %} installation access token or a {% data variables.product.pat_generic %} instead of `GITHUB_TOKEN` when creating or updating the pull request. +{% endif %} + {% data reusables.actions.actions-do-not-trigger-pages-rebuilds %} ## Next steps diff --git a/content/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow.md b/content/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow.md index ed93ed0ef4e5..3915f0c0786d 100644 --- a/content/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow.md +++ b/content/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow.md @@ -25,7 +25,7 @@ To learn more about workflows and triggering workflows, see [AUTOTITLE](/actions {% data reusables.actions.actions-do-not-trigger-workflows %} For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). -If you do want to trigger a workflow from within a workflow run, you can use a {% data variables.product.prodname_github_app %} installation access token or a {% data variables.product.pat_generic %} instead of `GITHUB_TOKEN` to trigger events that require a token. +If you do want to trigger a workflow from within a workflow run, you can use a {% data variables.product.prodname_github_app %} installation access token or a {% data variables.product.pat_generic %} instead of `GITHUB_TOKEN` to trigger events that require a token.{% ifversion actions-github-token-pull-request-approval %} Using one of these alternatives also lets `pull_request` workflows run automatically (without the approval prompt described above) when the pull request is created or updated by automation.{% endif %} If you use a {% data variables.product.prodname_github_app %}, you'll need to create a {% data variables.product.prodname_github_app %} and store the app ID and private key as secrets. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). If you use a {% data variables.product.pat_generic %}, you'll need to create a {% data variables.product.pat_generic %} and store it as a secret. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). diff --git a/content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md b/content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md index 2f38e2ff8ccb..8200163e56f9 100644 --- a/content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md +++ b/content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md @@ -510,7 +510,8 @@ on: > [!NOTE] > * {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request). By default, a workflow only runs when a `pull_request` event's activity type is `opened`, `synchronize`, or `reopened`. To trigger workflows by different activity types, use the `types` keyword. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onevent_nametypes). > * Workflows will not run on `pull_request` activity if the pull request has a merge conflict. The merge conflict must be resolved first. Conversely, workflows with the `pull_request_target` event will run even if the pull request has a merge conflict. Before using the `pull_request_target` trigger, you should be aware of the security risks. For more information, see [`pull_request_target`](#pull_request_target). -> * The `pull_request` webhook event payload is empty for merged pull requests and pull requests that come from forked repositories. +> * The `pull_request` webhook event payload is empty for merged pull requests and pull requests that come from forked repositories.{% ifversion actions-github-token-pull-request-approval %} +> * When a pull request is created or updated by a workflow using `GITHUB_TOKEN`, `pull_request` events with the `opened`, `synchronize`, or `reopened` activity types create workflow runs that require approval. A user with write access to the repository can approve these runs from the pull request page. With the exception of `workflow_dispatch` and `repository_dispatch`, other `GITHUB_TOKEN`-triggered events do not create workflow runs at all.{% endif %} > * The value of `GITHUB_REF` varies for a closed pull request depending on whether the pull request has been merged or not. If a pull request was closed but not merged, it will be `refs/pull/PULL_REQUEST_NUMBER/merge`. If a pull request was closed as a result of being merged, it will be the fully qualified `ref` of the branch it was merged into, for example `/refs/heads/main`. Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated. For activity related to pull request reviews, pull request review comments, or pull request comments, use the [`pull_request_review`](#pull_request_review), [`pull_request_review_comment`](#pull_request_review_comment), or [`issue_comment`](#issue_comment) events instead. For information about the pull request APIs, see [AUTOTITLE](/graphql/reference/objects#pullrequest) in the GraphQL API documentation or [AUTOTITLE](/rest/pulls). diff --git a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md b/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md index a38f8124df53..adeb3a25ec27 100644 --- a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md +++ b/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md @@ -117,160 +117,6 @@ For more information about best practices, see [AUTOTITLE](/rest/overview/keepin If you selected an organization as the resource owner and the organization requires approval for {% data variables.product.pat_v2 %}s, then your token will be marked as `pending` until it is reviewed by an organization administrator. Your token will only be able to read public resources until it is approved. If you are an owner of the organization, your request is automatically approved. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization). -### Pre-filling {% data variables.product.pat_v2 %} details using URL parameters - -You can share templates for a {% data variables.product.pat_v2 %} via links. Storing token details this way makes it easier to automate workflows and improve your developer experience by directing users to token creation with relevant fields already completed. - -Each supported field can be set using a specific query parameter. All parameters are optional and validated by the token generation form to ensure that the combinations of permissions and resource owner makes sense. - -An example URL template is shown here, with line breaks for legibility: - -```http copy -https://github.com/settings/personal-access-tokens/new - ?name=Repo-reading+token - &description=Just+contents:read - &target_name=octodemo - &expires_in=45 - &contents=read -``` - -Try the URL to create a token with `contents:read` and `metadata:read`, with the given name and description and an expiration date 45 days in the future. You'll see an error message indicating `Cannot find the specified resource owner: octodemo` because you're not a member of the `octodemo` organization. - -Below are some example URLs that generate the tokens we see most often: - -* [Read repo contents](https://github.com/settings/personal-access-tokens/new?name=Repo-reading+token&description=Just+contents:read&contents=read) -* [Push access to repos](https://github.com/settings/personal-access-tokens/new?name=Repo-writing+token&description=Just+contents:write&contents=write) -* [GitHub Models access](https://github.com/settings/personal-access-tokens/new?name=GitHub+Models+token&description=Used%20to%20call%20GitHub%20Models%20APIs%20to%20easily%20run%20LLMs%3A%20https%3A%2F%2Fdocs.github.com%2Fgithub-models%2Fquickstart%23step-2-make-an-api-call&user_models=read) -* [Update code and open a PR](https://github.com/settings/personal-access-tokens/new?name=Core-loop+token&description=Write%20code%20and%20push%20it%20to%20main%21%20Includes%20permission%20to%20edit%20workflow%20files%20for%20Actions%20-%20remove%20%60workflows%3Awrite%60%20if%20you%20don%27t%20need%20to%20do%20that&contents=write&pull_requests=write&workflows=write) -* [Manage Copilot licenses in an organization](https://github.com/settings/personal-access-tokens/new?name=Core-loop+token&description=Enable%20or%20disable%20copilot%20access%20for%20users%20with%20the%20Seat%20Management%20APIs%3A%20https%3A%2F%2Fdocs.github.com%2Frest%2Fcopilot%2Fcopilot-user-management%0ABe%20sure%20to%20select%20an%20organization%20for%20your%20resource%20owner%20below%21&organization_copilot_seat_management=write) -* [Make Copilot requests](https://github.com/settings/personal-access-tokens/new?name=Copilot+requests+token&description=Make%20Copilot%20API%20requests%20on%20behalf%20of%20the%20user%2C%20consuming%20premium%20requests%3A%20https%3A%2F%2Fdocs.github.com%2Fcopilot%2Fconcepts%2Fbilling%2Fcopilot-requests&user_copilot_requests=read) - -#### Supported Query Parameters - -To create your own token template, follow the query parameter details provided in this table: - -| Parameter | Type | Example Value | Valid Values | Description | -|----------------|--------|------------------|--------------|-----------------------| -| `name` | string | `Deploy%20Bot` | ≤ 40 characters, URL-encoded | Pre-fills the token’s display name. | -| `description` | string | `Used+for+deployments` | ≤ 1024 chars, URL-encoded | Pre-fills the description for the token. | -| `target_name` | string | `octodemo` | User or organization slug | Sets the token's resource target. This is the owner of the repositories that the token will be able to access. If not provided, defaults to the current user's account. | -| `expires_in` | integer| `30` or `none` | Integer between 1 and 366, or `none` | Days until expiration or `none` for non-expiring. If not provided, the default is 30 days, or less if the target has a token lifetime policy set. | -| `` | string | `contents=read` | A series of permission and access levels. | The permissions the token should have. Permissions can be set to `read`, `write`, or `admin`, but not every permission supports each of those levels. | - -#### Permissions - -Each supported permission is set using its name as a query parameter, with the value specifying the desired access level. Valid access levels are `read`, `write`, and `admin`. Some permissions only support `read`, some only support `write`, and only a few have `admin`. Use as many permissions as needed, in the form `&contents=read&pull_requests=write&...`. - -You do not need to include both `read` and `write` for a permission in your URL—`write` always includes `read`, and `admin` always includes `write`. - -##### Account Permissions - -Account permissions are only used when the current user is set as the resource owner. - -| Parameter name | Display name | Access levels | -|---|---|---| -| `blocking` | Block another user | `read`, `write` | -| `codespaces_user_secrets` | Codespaces user secrets | `read`, `write` | -| `copilot_messages` | Copilot Chat | `read` | -| `copilot_editor_context` | Copilot Editor Context | `read` | -| `copilot_requests` | Copilot requests | `write` | -| `emails` | Email addresses | `read`, `write` | -| `user_events` | Events | `read` | -| `followers` | Followers | `read`, `write` | -| `gpg_keys` | GPG keys | `read`, `write` | -| `gists` | Gists | `write` | -| `keys` | Git SSH keys | `read`, `write` | -| `interaction_limits` | Interaction limits | `read`, `write` | -| `knowledge_bases` | Knowledge bases | `read`, `write` | -| `user_models` | Models | `read` | -| `plan` | Plan | `read` | -| `private_repository_invitations` | Private repository invitations | `read` | -| `profile` | Profile | `write` | -| `git_signing_ssh_public_keys` | SSH signing keys | `read`, `write` | -| `starring` | Starring | `read`, `write` | -| `watching` | Watching | `read`, `write` | - -{% ifversion copilot %} - -> [!NOTE] -> The `copilot_requests` permission enables making {% data variables.product.prodname_copilot_short %} requests for the given user, which count towards the user's premium request allowance or are charged to overage billing if the allowance is exceeded. For more information about {% data variables.product.prodname_copilot_short %} requests and billing, see [AUTOTITLE](/copilot/concepts/billing/copilot-requests). - -{% endif %} -##### Repository Permissions - -Repository permissions work for both user and organization resource owners. - -| Parameter name | Display name | Access levels | -|---|---|---| -| `actions` | Actions | `read`, `write` | -| `administration` | Administration | `read`, `write` | -| {% ifversion artifact-metadata %} | -| `artifact_metadata` | Artifact Metadata | `read`, `write` | -| {% endif %} | -| `attestations` | Attestations | `read`, `write` | -| {% ifversion code-quality %} | -| `code_quality` | Code quality | `read`, `write` | -| {% endif %} | -| `security_events` | Code scanning alerts | `read`, `write` | -| `codespaces` | Codespaces | `read`, `write` | -| `codespaces_lifecycle_admin` | Codespaces lifecycle admin | `read`, `write` | -| `codespaces_metadata` | Codespaces metadata | `read` | -| `codespaces_secrets` | Codespaces secrets | `write` | -| `statuses` | Commit statuses | `read`, `write` | -| `contents` | Contents | `read`, `write` | -| `repository_custom_properties` | Custom properties | `read`, `write` | -| `vulnerability_alerts` | Dependabot alerts | `read`, `write` | -| `dependabot_secrets` | Dependabot secrets | `read`, `write` | -| `deployments` | Deployments | `read`, `write` | -| `discussions` | Discussions | `read`, `write` | -| `environments` | Environments | `read`, `write` | -| `issues` | Issues | `read`, `write` | -| `merge_queues` | Merge queues | `read`, `write` | -| `metadata` | Metadata | `read` | -| `pages` | Pages | `read`, `write` | -| `pull_requests` | Pull requests | `read`, `write` | -| `repository_advisories` | Repository security advisories | `read`, `write` | -| `secret_scanning_alerts` | Secret scanning alerts | `read`, `write` | -| `secrets` | Secrets | `read`, `write` | -| `actions_variables` | Variables | `read`, `write` | -| `repository_hooks` | Webhooks | `read`, `write` | -| `workflows` | Workflows | `write` | - -##### Organization Permissions - -Organization permissions can only be used if the resource owner is an organization. - -| Parameter name | Display name | Access levels | -|---|---|---| -| `organization_api_insights` | API Insights | `read` | -| `organization_administration` | Administration | `read`, `write` | -| `organization_user_blocking` | Blocking users | `read`, `write` | -| `organization_campaigns` | Campaigns | `read`, `write` | -| `organization_custom_org_roles` | Custom organization roles | `read`, `write` | -| `organization_custom_properties` | Custom repository properties | `read`, `write`, `admin` | -| `organization_custom_roles` | Custom repository roles | `read`, `write` | -| `organization_events` | Events | `read` | -| `organization_copilot_seat_management` | GitHub Copilot Business | `read`, `write` | -| `issue_types` | Issue Types | `read`, `write` | -| `organization_knowledge_bases` | Knowledge bases | `read`, `write` | -| `members` | Members | `read`, `write` | -| `organization_models` | Models | `read` | -| `organization_network_configurations` | Network configurations | `read`, `write` | -| `organization_announcement_banners` | Organization announcement banners | `read`, `write` | -| `organization_codespaces` | Organization codespaces | `read`, `write` | -| `organization_codespaces_secrets` | Organization codespaces secrets | `read`, `write` | -| `organization_codespaces_settings` | Organization codespaces settings | `read`, `write` | -| `organization_dependabot_secrets` | Organization dependabot secrets | `read`, `write` | -| `organization_code_scanning_dismissal_requests` | Code scanning dismissal requests | `read`, `write` | -| `organization_private_registries` | Private registries | `read`, `write` | -| `organization_plan` | Plan | `read` | -| `organization_projects` | Projects | `read`, `write`, `admin` | -| `organization_secrets` | Secrets | `read`, `write` | -| `organization_self_hosted_runners` | Self-hosted runners | `read`, `write` | -| `team_discussions` | Team discussions | `read`, `write` | -| `organization_actions_variables` | Variables | `read`, `write` | -| `organization_hooks` | Webhooks | `read`, `write` | - ## Creating a {% data variables.product.pat_v1 %} > [!NOTE] diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository.md index e152f82c1eb1..f5e49f877376 100644 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository.md +++ b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository.md @@ -71,9 +71,6 @@ Here is the rendered version of the issue form. You can encourage contributors to use issue templates by setting `blank_issues_enabled` to `false`. If you set `blank_issues_enabled` to `true`, everyone with access to the repository will see the **Blank issue** option in the template chooser. When `blank_issues_enabled` is set to `false`, users with write access or above (Write, Maintain, or Admin roles) will still see the **Blank issue** option in the template chooser, labeled **Maintainers only**. Contributors with Read or Triage roles will only see the configured templates. -> [!NOTE] -> If you used the legacy workflow to manually create an `issue_template.md` file in the `.github` folder and enable blank issues in your _config.yml_ file, the template in `issue_template.md` will be used when people choose to open a blank issue. If you disable blank issues, the template will never be used. - If you prefer to receive certain reports outside of {% data variables.product.github %}, you can direct people to external sites with `contact_links`. Here is an example _config.yml_ file. diff --git a/content/contributing/style-guide-and-content-model/get-started-content-type.md b/content/contributing/style-guide-and-content-model/get-started-content-type.md new file mode 100644 index 000000000000..a2d8221dd50c --- /dev/null +++ b/content/contributing/style-guide-and-content-model/get-started-content-type.md @@ -0,0 +1,30 @@ +--- +title: Get started content type +intro: Get started content provides the minimal essential information to use a product or feature. +versions: + fpt: '*' + ghec: '*' + ghes: '*' +category: + - Follow the style guide and content model +--- + +Get started content provides an entry point into using GitHub products and features. This section should contain only the minimum essential information a user needs before they move on to concepts and how-tos. We do this to be concise, and also so it doesn't seem complicated just to get started with a feature. + +## Get started considerations + +Get started is a set of articles which should be easy and fast to scan. It should contain fewer than 5 articles, and ideally only two: +* Quickstart +* About [PRODUCT] (or “What is [PRODUCT]”) + +The one exception to this may be with available plans and billing information, where such information is required to use the product or feature. + +For more information on quickstart content, see [AUTOTITLE](/contributing/style-guide-and-content-model/quickstart-content-type). + +In particular, articles with this information do not belong in Get started: + * Articles that fall under the how-to content type. + * Set up or sign up steps: these are also how-tos. They document how to do something in the UI. + * Content that is useful for getting started with a particular feature but not the whole product area. This kind of content more properly belongs in Concepts. + * Best practices, generally. Users new to a feature lack the context necessary to make the most of these. + + diff --git a/content/contributing/style-guide-and-content-model/index.md b/content/contributing/style-guide-and-content-model/index.md index d2f97a6d2b53..8124355d0d00 100644 --- a/content/contributing/style-guide-and-content-model/index.md +++ b/content/contributing/style-guide-and-content-model/index.md @@ -14,6 +14,7 @@ children: - /how-to-content-type - /troubleshooting-content-type - /release-note-content-type + - /get-started-content-type - /quickstart-content-type - /tutorial-content-type - /about-combining-multiple-content-types diff --git a/content/copilot/concepts/index.md b/content/copilot/concepts/index.md index c26623f9a859..2436d3183b39 100644 --- a/content/copilot/concepts/index.md +++ b/content/copilot/concepts/index.md @@ -13,15 +13,14 @@ children: - /prompting - /context - /tools - - /auto-model-selection + - /models - /usage-limits - /billing - /about-enterprise-accounts-for-copilot-business - /policies - /mcp-management - - /fedramp-models - /network-settings - - /fallback-and-lts-models - /preparing-for-new-features-and-models contentType: concepts --- + diff --git a/content/copilot/concepts/auto-model-selection.md b/content/copilot/concepts/models/auto-model-selection.md similarity index 93% rename from content/copilot/concepts/auto-model-selection.md rename to content/copilot/concepts/models/auto-model-selection.md index db943cd790e0..829277d127f9 100644 --- a/content/copilot/concepts/auto-model-selection.md +++ b/content/copilot/concepts/models/auto-model-selection.md @@ -7,8 +7,10 @@ product: '{% data variables.copilot.copilot_auto_model_selection_short_cap_a %} versions: feature: copilot contentType: concepts -category: +category: - Learn about Copilot +redirect_from: + - /copilot/concepts/auto-model-selection --- ## Overview @@ -17,14 +19,14 @@ More than just a model picker, {% data variables.copilot.copilot_auto_model_sele ### Auto with task optimization -> [!NOTE] {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} with task optimization is generally available in {% data variables.copilot.copilot_chat_short %} in {% data variables.product.prodname_vscode_shortname %}. +> [!NOTE] {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} with task optimization is generally available in {% data variables.copilot.copilot_chat_short %} in {% data variables.product.prodname_vscode_shortname %}. {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} with task optimization combines two systems to provide high quality results and better reliability. One system tracks real-time system health and availability, while the other evaluates task complexity. Putting these together, {% data variables.copilot.copilot_auto_model_selection_short %} routes the task to the optimal model. -Routing occurs along natural cache boundaries to avoid additional cache related costs. Switching models mid-session has shown increased cost without ample improvements in quality. +Routing occurs along natural cache boundaries to avoid additional cache related costs. Switching models mid-session has shown increased cost without ample improvements in quality. This helps you get more value from {% data variables.product.prodname_copilot_short %} since it matches each task to the model that can solve it most efficiently. That means reserving higher-cost reasoning models for problems that truly need it, while routing straightforward tasks to faster, lower-cost models that still deliver great results. -Benefits of using {% data variables.copilot.copilot_auto_model_selection_short %} include: +Benefits of using {% data variables.copilot.copilot_auto_model_selection_short %} include: * Matching each task to the model that can solve it most efficiently. * Model choice based on real-time system health and availability. * Language invariance: Routing decisions depend on what you are trying to do, not what language you're asking in. @@ -46,7 +48,7 @@ When you select **Auto**, {% data variables.copilot.copilot_auto_model_selection * Models not available in your plan. * Models excluded by administrator policies. See [AUTOTITLE](/copilot/how-tos/copilot-on-github/set-up-copilot/configure-access-to-ai-models). * Models excluded by policies restricting {% data variables.product.prodname_copilot_short %} to data-resident or FedRAMP-compliant models. -* Models with premium request multipliers greater than one. +* Models with premium request multipliers greater than one. ### Multiplier discounts @@ -54,20 +56,20 @@ When you select **Auto**, {% data variables.copilot.copilot_auto_model_selection ## {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} in {% data variables.product.prodname_copilot_short %} -{% data variables.copilot.copilot_auto_model_selection_short_cap_a %}, optimized for model reliability and availability, is available in these {% data variables.product.prodname_copilot_short %} products: +{% data variables.copilot.copilot_auto_model_selection_short_cap_a %}, optimized for model reliability and availability, is available in these {% data variables.product.prodname_copilot_short %} products: * {% data variables.copilot.copilot_chat_short %} * {% data variables.copilot.copilot_cli_short %} -* {% data variables.copilot.copilot_cloud_agent %} +* {% data variables.copilot.copilot_cloud_agent %} > [!TIP] > You can see which model was used for each {% data variables.product.prodname_copilot_short %} response. > * In **{% data variables.copilot.copilot_chat_short %}**, hover over the response. > * In **{% data variables.copilot.copilot_cli_short %}**, the model used for each response displays in the terminal. -> * In **{% data variables.copilot.copilot_cloud_agent %}**, the model used for each response displays at the end of the response. +> * In **{% data variables.copilot.copilot_cloud_agent %}**, the model used for each response displays at the end of the response. ### {% data variables.copilot.copilot_chat_short %} in IDEs -{% data variables.copilot.copilot_auto_model_selection_short_cap_a %}, with task optimization, is generally available in the following IDEs: +{% data variables.copilot.copilot_auto_model_selection_short_cap_a %}, with task optimization, is generally available in the following IDEs: * {% data variables.product.prodname_vscode_shortname %} {% data variables.copilot.copilot_auto_model_selection_short_cap_a %}, optimized for model reliability and availability, is generally available in the following IDEs: @@ -75,7 +77,7 @@ When you select **Auto**, {% data variables.copilot.copilot_auto_model_selection * Eclipse * Xcode -{% data variables.copilot.copilot_auto_model_selection_short_cap_a %}, optimized for model reliability and availability, is in public preview in the following IDEs: +{% data variables.copilot.copilot_auto_model_selection_short_cap_a %}, optimized for model reliability and availability, is in public preview in the following IDEs: * {% data variables.product.prodname_vs %} #### Enabling access during {% data variables.release-phases.public_preview %} @@ -88,7 +90,7 @@ When you select **Auto** in the {% data variables.product.prodname_openai_codex ### {% data variables.product.prodname_openai_codex %} supported models -These models are available for {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} in the {% data variables.product.prodname_openai_codex %} coding agent. +These models are available for {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} in the {% data variables.product.prodname_openai_codex %} coding agent. {% data reusables.copilot.openai-codex-agent-models %} @@ -96,7 +98,7 @@ For more information, see [AUTOTITLE](/copilot/concepts/agents/openai-codex). ### {% data variables.product.prodname_anthropic_claude %} supported models -These models are available for {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} in the {% data variables.product.prodname_anthropic_claude %} coding agent. +These models are available for {% data variables.copilot.copilot_auto_model_selection_short_cap_a %} in the {% data variables.product.prodname_anthropic_claude %} coding agent. {% data reusables.copilot.anthropic-claude-agent-models %} diff --git a/content/copilot/concepts/fallback-and-lts-models.md b/content/copilot/concepts/models/fallback-and-lts-models.md similarity index 92% rename from content/copilot/concepts/fallback-and-lts-models.md rename to content/copilot/concepts/models/fallback-and-lts-models.md index 8ef077b72391..740d888bfb84 100644 --- a/content/copilot/concepts/fallback-and-lts-models.md +++ b/content/copilot/concepts/models/fallback-and-lts-models.md @@ -1,13 +1,15 @@ --- title: Base and long-term support (LTS) models shortTitle: Base and LTS models -intro: 'Learn about base models, long-term support (LTS) models, and how they affect model availability for enterprises using {% data variables.product.prodname_copilot %}.' +intro: Learn about base models, long-term support (LTS) models, and how they affect model availability for enterprises using {% data variables.product.prodname_copilot %}. versions: feature: copilot allowTitleToDifferFromFilename: true contentType: concepts category: - Manage Copilot for a team +redirect_from: + - /copilot/concepts/fallback-and-lts-models --- ## About base models diff --git a/content/copilot/concepts/fedramp-models.md b/content/copilot/concepts/models/fedramp-models.md similarity index 91% rename from content/copilot/concepts/fedramp-models.md rename to content/copilot/concepts/models/fedramp-models.md index f4249af03257..21239e286f9c 100644 --- a/content/copilot/concepts/fedramp-models.md +++ b/content/copilot/concepts/models/fedramp-models.md @@ -1,11 +1,13 @@ --- title: FedRAMP-compliant models for GitHub Copilot shortTitle: FedRAMP models -intro: "Restrict users to models with FedRAMP Moderate certification." +intro: Restrict users to models with FedRAMP Moderate certification. versions: feature: copilot product: '{% data variables.enterprise.data_residency %}' contentType: concepts +redirect_from: + - /copilot/concepts/fedramp-models --- If your enterprise uses {% data variables.enterprise.data_residency %} in the US, you can enable a policy to ensure that users on your {% data variables.product.prodname_copilot_short %} plan can only use models with **FedRAMP Moderate** certification. @@ -34,4 +36,4 @@ Enabling the FedRAMP policy restricts users to the following models: To enable this policy, use the **Restrict {% data variables.product.prodname_copilot_short %} to FedRAMP models** policy in the "Features" section of your enterprise's {% data variables.product.prodname_copilot_short %} policies. This policy is disabled by default, and enabling it will affect your pricing for {% data variables.product.prodname_copilot_short %} requests. -For instructions on finding your policies page, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies). \ No newline at end of file +For instructions on finding your policies page, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies). diff --git a/content/copilot/concepts/models/index.md b/content/copilot/concepts/models/index.md new file mode 100644 index 000000000000..0b1e12402048 --- /dev/null +++ b/content/copilot/concepts/models/index.md @@ -0,0 +1,14 @@ +--- +title: Models for GitHub Copilot +shortTitle: Models +intro: Learn about the AI models available for {% data variables.product.prodname_copilot %}. +versions: + feature: copilot +contentType: concepts +children: + - /utility-models + - /auto-model-selection + - /fedramp-models + - /fallback-and-lts-models +--- + diff --git a/content/copilot/concepts/models/utility-models.md b/content/copilot/concepts/models/utility-models.md new file mode 100644 index 000000000000..0f48b57db10b --- /dev/null +++ b/content/copilot/concepts/models/utility-models.md @@ -0,0 +1,24 @@ +--- +title: Utility models +intro: 'Utility models power background {% data variables.product.prodname_copilot_short %} features.' +versions: + feature: copilot +contentType: concepts +--- + +Utility models are a small set of models that are automatically enabled for all {% data variables.product.prodname_copilot %} users across every plan. They power background features such as the generation of commit messages or chat session titles, and they apply across {% data variables.product.prodname_copilot_short %} surfaces: in IDEs, on {% data variables.product.github %}, and in {% data variables.copilot.copilot_cli_short %}. + +## How do utility models work? + +Utility models: + +* Are **not** visible in the model picker and cannot be selected by users directly. +* **Cannot** be disabled by organization or enterprise administrators, except by disabling {% data variables.product.prodname_copilot_short %} completely. +* Do **not** consume premium request units or tokens for usage-based billing, and do **not** appear as a billed line item in usage reports. +* **Are** subject to per-user rate limits. + +These characteristics ensure that {% data variables.product.prodname_copilot_short %} features work smoothly regardless of your model policies and billing controls. + +## List of utility models + +Utility models are typically selected for being fast and lightweight. {% data reusables.copilot.utility-models %} diff --git a/content/copilot/concepts/preparing-for-new-features-and-models.md b/content/copilot/concepts/preparing-for-new-features-and-models.md index 59346a561881..d5d80318ff4a 100644 --- a/content/copilot/concepts/preparing-for-new-features-and-models.md +++ b/content/copilot/concepts/preparing-for-new-features-and-models.md @@ -54,18 +54,21 @@ You can find information about the models available and upcoming models in the f * **Model comparison**: To compare model capabilities side by side, see [AUTOTITLE](/copilot/reference/ai-models/model-comparison). * **Changelog**: Model updates are announced in the [{% data variables.product.prodname_copilot_short %} changelog](https://github.blog/changelog/label/copilot/). -To plan for model transitions and set user expectations, track which models {% data variables.product.github %} designates as base or long-term support (LTS): +#### Special categories + +{% data variables.product.company_short %} categorizes certain types of model, allowing you to plan for model transitions and set user expectations. {% rowheaders %} | Model type | Description | Why it matters | | --- | --- | --- | +| Utility model | A small set of models that power background {% data variables.product.company_short %} features across surfaces. | Your enterprise cannot disable these models. Monitor these to ensure they are compliant. | | Base model | The default model when no other models are enabled. | Automatically enabled within 60 days of designation. | | LTS model | A model supported for one year from designation. | Allows enterprises to build workflows around a stable model. | {% endrowheaders %} -For more information, see [AUTOTITLE](/copilot/concepts/fallback-and-lts-models). +For more information, see [AUTOTITLE](/copilot/concepts/models/utility-models) and [AUTOTITLE](/copilot/concepts/models/fallback-and-lts-models). ## Considering different release stages diff --git a/content/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk/authenticate-copilot-sdk.md b/content/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk/authenticate-copilot-sdk.md index 9d2291247b5a..e11d143a9006 100644 --- a/content/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk/authenticate-copilot-sdk.md +++ b/content/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk/authenticate-copilot-sdk.md @@ -56,7 +56,7 @@ Use an OAuth {% data variables.product.github %} App to authenticate users throu **How it works:** 1. User authorizes your OAuth {% data variables.product.github %} App. 1. Your app receives a user access token (`gho_` or `ghu_` prefix). -1. Pass the token to the SDK via the `githubToken` option. +1. Pass the token to the SDK via the `gitHubToken` option. **SDK configuration:** @@ -64,7 +64,7 @@ Use an OAuth {% data variables.product.github %} App to authenticate users throu import { CopilotClient } from "@github/copilot-sdk"; const client = new CopilotClient({ - githubToken: userAccessToken, // Token from OAuth flow + gitHubToken: userAccessToken, // Token from OAuth flow useLoggedInUser: false, // Don't use stored CLI credentials }); ``` @@ -130,7 +130,7 @@ For complete setup instructions, including provider configuration options, limit When multiple authentication methods are available, the SDK uses them in this priority order: -1. **Explicit `githubToken`** — Token passed directly to the SDK constructor +1. **Explicit `gitHubToken`** — Token passed directly to the SDK constructor 1. **Direct API token** — `GITHUB_COPILOT_API_TOKEN` with `COPILOT_API_URL` 1. **Environment variable tokens** — `COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN` 1. **Stored OAuth credentials** — From previous `copilot` CLI sign-in diff --git a/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md b/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md index 0eb72b04fd22..fb5c039e2d26 100644 --- a/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md +++ b/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md @@ -24,7 +24,7 @@ The Microsoft Agent Framework is the unified successor to Semantic Kernel and Au | A2A protocol | Agent-to-Agent communication standard supported by the framework | > [!NOTE] -> MAF integration packages are available for .NET and Python. For TypeScript and Go, use the {% data variables.copilot.copilot_sdk_short %} directly—the standard SDK APIs provide tool calling, streaming, and custom agents. +> MAF integration packages are available for .NET and Python. For TypeScript, Go, and Java, use the {% data variables.copilot.copilot_sdk_short %} directly—the standard SDK APIs provide tool calling, streaming, and custom agents. ## Prerequisites @@ -317,5 +317,7 @@ catch (AgentException ex) ## Further reading * [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started) +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents) +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-skills) * [Microsoft Agent Framework documentation](https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot) * [Blog: Build AI Agents with GitHub Copilot SDK and Microsoft Agent Framework](https://devblogs.microsoft.com/semantic-kernel/build-ai-agents-with-github-copilot-sdk-and-microsoft-agent-framework/) diff --git a/content/copilot/how-tos/copilot-sdk/sdk-getting-started.md b/content/copilot/how-tos/copilot-sdk/sdk-getting-started.md index 02a12f23189f..00968124b058 100644 --- a/content/copilot/how-tos/copilot-sdk/sdk-getting-started.md +++ b/content/copilot/how-tos/copilot-sdk/sdk-getting-started.md @@ -144,4 +144,185 @@ unsubscribeIdle(); ## Next steps -To continue getting started with {% data variables.copilot.copilot_sdk_short %}, see [Build Your First Copilot-Powered App](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#step-4-add-a-custom-tool) in the `github/copilot-sdk` repository. +### Add a custom tool + +Give {% data variables.product.prodname_copilot_short %} the ability to call your code by defining a custom tool. Here's a weather lookup tool: + +```typescript copy +import { CopilotClient, defineTool } from "@github/copilot-sdk"; + +// Define a tool that Copilot can call +const getWeather = defineTool("get_weather", { + description: "Get the current weather for a city", + parameters: { + type: "object", + properties: { + city: { type: "string", description: "The city name" }, + }, + required: ["city"], + }, + handler: async (args: { city: string }) => { + const { city } = args; + // In a real app, you'd call a weather API here + const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]; + const temp = Math.floor(Math.random() * 30) + 50; + const condition = conditions[Math.floor(Math.random() * conditions.length)]; + return { city, temperature: `${temp}°F`, condition }; + }, +}); + +const client = new CopilotClient(); +const session = await client.createSession({ + model: "gpt-4.1", + streaming: true, + tools: [getWeather], +}); + +session.on("assistant.message_delta", (event) => { + process.stdout.write(event.data.deltaContent); +}); + +session.on("session.idle", () => { + console.log(); // New line when done +}); + +await session.sendAndWait({ + prompt: "What's the weather like in Seattle and Tokyo?", +}); + +await client.stop(); +process.exit(0); +``` + +For examples in Python, Go, .NET, and Rust, see [Getting started](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#step-4-add-a-custom-tool) in the `github/copilot-sdk` repository. {% data reusables.copilot.copilot-sdk.java-sdk-link %} + +When you define a tool, you're telling {% data variables.product.prodname_copilot_short %}: + +1. **What the tool does** (description) +1. **What parameters it needs** (schema) +1. **What code to run** (handler) + +{% data variables.product.prodname_copilot_short %} decides when to call your tool based on the user's question. When it does, the {% data variables.copilot.copilot_sdk_short %} runs your handler function and sends the result back to {% data variables.product.prodname_copilot_short %}, which incorporates it into the response. + +### Build an interactive assistant + +Combine everything into an interactive chat assistant: + +```typescript copy +import { CopilotClient, defineTool } from "@github/copilot-sdk"; +import * as readline from "readline"; + +const getWeather = defineTool("get_weather", { + description: "Get the current weather for a city", + parameters: { + type: "object", + properties: { + city: { type: "string", description: "The city name" }, + }, + required: ["city"], + }, + handler: async ({ city }) => { + const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]; + const temp = Math.floor(Math.random() * 30) + 50; + const condition = conditions[Math.floor(Math.random() * conditions.length)]; + return { city, temperature: `${temp}°F`, condition }; + }, +}); + +const client = new CopilotClient(); +const session = await client.createSession({ + model: "gpt-4.1", + streaming: true, + tools: [getWeather], +}); + +session.on("assistant.message_delta", (event) => { + process.stdout.write(event.data.deltaContent); +}); + +const rl = readline.createInterface({ + input: process.stdin, + output: process.stdout, +}); + +console.log("Weather Assistant (type 'exit' to quit)"); +console.log(" Try: 'What's the weather in Paris?'\n"); + +const prompt = () => { + rl.question("You: ", async (input) => { + if (input.toLowerCase() === "exit") { + await client.stop(); + rl.close(); + return; + } + + process.stdout.write("Assistant: "); + await session.sendAndWait({ prompt: input }); + console.log("\n"); + prompt(); + }); +}; + +prompt(); +``` + +Run with: + +```bash copy +npx tsx weather-assistant.ts +``` + +For examples in Python, Go, .NET, and Rust, see [Getting started](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#step-5-build-an-interactive-assistant) in the `github/copilot-sdk` repository. {% data reusables.copilot.copilot-sdk.java-sdk-link %} + +### Connect to MCP servers + +MCP (Model Context Protocol) servers provide pre-built tools. Connect to {% data variables.product.github %}'s MCP server to give {% data variables.product.prodname_copilot_short %} access to repositories, issues, and pull requests: + +```typescript copy +const session = await client.createSession({ + mcpServers: { + github: { + type: "http", + url: "https://api.githubcopilot.com/mcp/", + }, + }, +}); +``` + +For more information, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/mcp-servers). + +### Create custom agents + +Define specialized AI personas for specific tasks: + +```typescript copy +const session = await client.createSession({ + customAgents: [{ + name: "pr-reviewer", + displayName: "PR Reviewer", + description: "Reviews pull requests for best practices", + prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.", + }], +}); +``` + +For more information, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents). + +### Customize the system message + +Control the AI's behavior and personality by appending instructions: + +```typescript copy +const session = await client.createSession({ + systemMessage: { + content: "You are a helpful assistant for our engineering team. Always be concise.", + }, +}); +``` + +### Further reading + +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path) +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/agent-loop) +* [Connecting to an external CLI server](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#connecting-to-an-external-cli-server) in the `github/copilot-sdk` repository +* [Telemetry and observability](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#telemetry-and-observability) in the `github/copilot-sdk` repository diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli.md index ffaaf4d55b52..b87dd151d108 100644 --- a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli.md +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli.md @@ -1,50 +1,39 @@ --- -title: Using a bundled CLI with Copilot SDK +title: Default setup (bundled CLI) shortTitle: Bundled CLI -intro: Package {% data variables.copilot.copilot_cli_short %} alongside your application so that users do not need to install or configure anything separately. +intro: 'The Node.js, Python, and .NET SDKs include {% data variables.copilot.copilot_cli_short %} as a dependency—your app ships with everything it needs, with no extra installation or configuration required.' product: '{% data reusables.gated-features.copilot-sdk %}' versions: feature: copilot contentType: how-tos --- -{% data reusables.copilot.copilot-sdk.release-state-note %} +{% data reusables.copilot.copilot-sdk.technical-preview-note %} -Ship {% data variables.copilot.copilot_cli_short %} as part of your application so your users can get started with no additional setup. - -**Best for:** Desktop apps, standalone tools, Electron apps, and distributable CLI utilities. +**Best for:** Most applications—desktop apps, standalone tools, CLI utilities, prototypes, and more. ## How it works -Instead of relying on a globally installed CLI, you include the CLI binary in your application bundle. The SDK points to your bundled copy via the `cliPath` option. Key characteristics are: - -* The CLI binary ships with your app—no separate install is needed. -* You control the exact CLI version your app uses. -* Users authenticate through your app, environment variables, or BYOK. -* Sessions are managed per user on their machine. +When you install the {% data variables.copilot.copilot_sdk_short %}, {% data variables.copilot.copilot_cli_short %} is included automatically. The {% data variables.copilot.copilot_sdk_short %} starts it as a child process and communicates over stdio. There's nothing extra to configure. -## Setup +![Diagram showing how the SDK client includes the Copilot CLI binary and makes API calls to GitHub Copilot.](/assets/images/help/copilot/copilot-sdk/bundled-cli-architecture.png) -### Step 1: Include the CLI in your project +**Key characteristics:** -The CLI is distributed as part of the `@github/copilot` npm package. - -```shell -npm install @github/copilot -``` +* {% data variables.copilot.copilot_cli_short %} is included with the {% data variables.copilot.copilot_sdk_short %}—no separate install needed +* The {% data variables.copilot.copilot_sdk_short %} manages the CLI version to ensure compatibility +* Users authenticate through your app (or use env vars / BYOK) +* Sessions are managed per user on their machine -### Step 2: Point the SDK to your bundled CLI +> [!NOTE] +> The Go and Java SDKs do not bundle {% data variables.copilot.copilot_cli_short %}. You must install the CLI separately or set `cliPath` to point to an existing binary. See [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli) for details. -#### Node.js / TypeScript +## Quick start ```typescript import { CopilotClient } from "@github/copilot-sdk"; -import path from "path"; -const client = new CopilotClient({ - // Point to the CLI binary in your app bundle - cliPath: path.join(__dirname, "vendor", "copilot"), -}); +const client = new CopilotClient(); const session = await client.createSession({ model: "gpt-4.1" }); const response = await session.sendAndWait({ prompt: "Hello!" }); @@ -53,96 +42,41 @@ console.log(response?.data.content); await client.stop(); ``` -#### Python - -```python -from copilot import CopilotClient, PermissionHandler -from pathlib import Path - -client = CopilotClient({ - "cli_path": str(Path(__file__).parent / "vendor" / "copilot"), -}) -await client.start() - -session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1") -response = await session.send_and_wait({"prompt": "Hello!"}) -print(response.data.content) - -await client.stop() -``` - -#### Go - -```golang -client := copilot.NewClient(&copilot.ClientOptions{ - CLIPath: "./vendor/copilot", -}) -if err := client.Start(ctx); err != nil { - log.Fatal(err) -} -defer client.Stop() - -session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"}) -response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"}) -fmt.Println(*response.Data.Content) -``` - -#### .NET - -```csharp -var client = new CopilotClient(new CopilotClientOptions -{ - CliPath = Path.Combine(AppContext.BaseDirectory, "vendor", "copilot"), -}); - -await using var session = await client.CreateSessionAsync( - new SessionConfig { Model = "gpt-4.1" }); - -var response = await session.SendAndWaitAsync( - new MessageOptions { Prompt = "Hello!" }); -Console.WriteLine(response?.Data.Content); -``` +For examples in Python, Go, .NET, and Java, see [Default setup](https://github.com/github/copilot-sdk/blob/main/docs/setup/bundled-cli.md#quick-start) in the `github/copilot-sdk` repository. {% data reusables.copilot.copilot-sdk.java-sdk-link %} ## Authentication strategies -When bundling the CLI, you need to decide how your users will authenticate. The following diagram illustrates common patterns. +You need to decide how your users will authenticate. Here are the common patterns: -![Diagram showing authentication strategy options for a bundled CLI deployment.](/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png) +![Diagram showing authentication options for a bundled CLI: signed-in credentials, app-provided token, or BYOK.](/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png) -### Option A: User's signed-in credentials (simplest) +### Option A: user's signed-in credentials (simplest) -The user signs in to the CLI once, and your bundled app uses those credentials. No extra code needed—this is the default behavior. +The user signs in to {% data variables.copilot.copilot_cli_short %} once, and your app uses those credentials. No extra code needed—this is the default behavior. ```typescript -const client = new CopilotClient({ - cliPath: path.join(__dirname, "vendor", "copilot"), - // Default: uses signed-in user credentials -}); +const client = new CopilotClient(); +// Default: uses signed-in user credentials ``` -### Option B: Token via environment variable +### Option B: token via environment variable -Set a token programmatically or instruct users to set one before starting your app: +Ship your app with instructions to set a token, or set it programmatically: ```typescript const client = new CopilotClient({ - cliPath: path.join(__dirname, "vendor", "copilot"), env: { - COPILOT_GITHUB_TOKEN: getUserToken(), + COPILOT_GITHUB_TOKEN: getUserToken(), // Your app provides the token }, }); ``` -Replace `getUserToken()` with the logic in your app that retrieves the user's {% data variables.product.github %} OAuth token. +### Option C: BYOK (no {% data variables.product.github %} auth needed) -### Option C: BYOK (no {% data variables.product.github %} authentication needed) - -If you manage your own model provider keys, users don't need {% data variables.product.github %} accounts: +If you manage your own model provider keys, users don't need {% data variables.product.github %} accounts at all: ```typescript -const client = new CopilotClient({ - cliPath: path.join(__dirname, "vendor", "copilot"), -}); +const client = new CopilotClient(); const session = await client.createSession({ model: "gpt-4.1", @@ -154,14 +88,14 @@ const session = await client.createSession({ }); ``` +See [AUTOTITLE](/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk/bring-your-own-key) for full details. + ## Session management -Bundled apps typically want named sessions so users can resume conversations: +Apps typically want named sessions so users can resume conversations: ```typescript -const client = new CopilotClient({ - cliPath: path.join(__dirname, "vendor", "copilot"), -}); +const client = new CopilotClient(); // Create a session tied to the user's project const sessionId = `project-${projectName}`; @@ -170,86 +104,23 @@ const session = await client.createSession({ model: "gpt-4.1", }); -// Resume the session in a later run +// User closes app... +// Later, resume where they left off const resumed = await client.resumeSession(sessionId); ``` -Session state is stored at `~/.copilot/session-state/SESSION-ID/`, where `SESSION-ID` is the session ID you provided. - -## Distribution patterns - -### Desktop app (Electron, Tauri) - -Include the CLI binary in your app's resources directory: - -```typescript -import { app } from "electron"; -import path from "path"; - -const cliPath = path.join( - app.isPackaged ? process.resourcesPath : __dirname, - "copilot" -); - -const client = new CopilotClient({ cliPath }); -``` - -### CLI tool - -For distributable CLI tools, resolve the path relative to your binary: - -```typescript -import { fileURLToPath } from "url"; -import path from "path"; - -const __dirname = path.dirname(fileURLToPath(import.meta.url)); -const cliPath = path.join(__dirname, "..", "vendor", "copilot"); - -const client = new CopilotClient({ cliPath }); -``` - -## Platform-specific binaries - -When distributing for multiple platforms, include the correct binary for each target: - -```text -my-app/ -├── vendor/ -│ ├── copilot-darwin-arm64 # macOS Apple Silicon -│ ├── copilot-darwin-x64 # macOS Intel -│ ├── copilot-linux-x64 # Linux x64 -│ └── copilot-win-x64.exe # Windows x64 -└── src/ - └── index.ts -``` - -```typescript -import os from "os"; - -function getCLIPath(): string { - const platform = process.platform; // "darwin", "linux", "win32" - const arch = os.arch(); // "arm64", "x64" - const ext = platform === "win32" ? ".exe" : ""; - const name = `copilot-${platform}-${arch}${ext}`; - return path.join(__dirname, "vendor", name); -} - -const client = new CopilotClient({ - cliPath: getCLIPath(), -}); -``` +Session state persists at `~/.copilot/session-state/{sessionId}/`. -## Limitations +## When to move on -| Limitation | Details | -|---|---| -| **Bundle size** | The CLI binary adds to your app's distribution size. | -| **Updates** | You manage CLI version updates in your release cycle. | -| **Platform builds** | Separate binaries are needed for each OS/architecture. | -| **Single user** | Each bundled CLI instance serves one user. | +| Need | Next guide | +|------|-----------| +| Users signing in with {% data variables.product.github %} accounts | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth) | +| Run on a server instead of user machines | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services) | +| Use your own model keys | [AUTOTITLE](/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk/bring-your-own-key) | ## Next steps -* For users signing in with {% data variables.product.github %} accounts, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth). -* To run on a server instead of user machines, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services). -* For installation and your first message, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started). +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk/bring-your-own-key) +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/session-persistence) +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started) diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path.md index 797b84b0d8a2..4fc995c92c04 100644 --- a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path.md +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path.md @@ -22,8 +22,8 @@ You're building a personal assistant, side project, or experimental app. You wan **Start with:** -1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli)—use the CLI already signed in on your machine. -1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli)—package everything into a standalone app. +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli)—the SDK includes the CLI automatically—just install and go. +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli)—use your own CLI binary or running instance (advanced). ### Internal app developer @@ -72,8 +72,8 @@ Use this table to find the right guide based on what you need to do. | What you need | Guide | |---|---| -| Simplest possible setup | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli) | -| Ship a standalone app with Copilot | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli) | +| Getting started quickly | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli) | +| Use your own CLI binary or server | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli) | | Users sign in with {% data variables.product.github %} | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth) | | Use your own model keys (OpenAI, Azure, etc.) | [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/auth/byok.md) in the `github/copilot-sdk` repository | | Azure BYOK with Managed Identity (no API keys) | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/azure-managed-identity) | @@ -84,13 +84,11 @@ Use this table to find the right guide based on what you need to do. All guides assume you have: -* **{% data variables.copilot.copilot_cli_short %}** installed. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). -* **One of the SDKs** installed: +* **One of the SDKs** installed (Node.js, Python, and .NET SDKs include {% data variables.copilot.copilot_cli_short %} automatically): * Node.js: `npm install @github/copilot-sdk` * Python: `pip install github-copilot-sdk` - * Go: `go get github.com/github/copilot-sdk/go` + * Go: `go get github.com/github/copilot-sdk/go` (requires separate CLI installation) * .NET: `dotnet add package GitHub.Copilot.SDK` - * Java: See the [`github/copilot-sdk-java`](https://github.com/github/copilot-sdk-java) repository for Maven/Gradle setup If you're new to the {% data variables.copilot.copilot_sdk %}, start with [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started) first, then return here for production configuration. diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth.md index 2f57944e05ae..c973e12b1228 100644 --- a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth.md +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth.md @@ -74,7 +74,7 @@ import { CopilotClient } from "@github/copilot-sdk"; // Create a client for an authenticated user function createClientForUser(userToken: string): CopilotClient { return new CopilotClient({ - githubToken: userToken, + gitHubToken: userToken, useLoggedInUser: false, // Don't fall back to CLI sign-in }); } @@ -196,7 +196,7 @@ For {% data variables.enterprise.prodname_managed_users %}, the flow is identica ```typescript // No special SDK configuration needed for EMU const client = new CopilotClient({ - githubToken: emuUserToken, + gitHubToken: emuUserToken, useLoggedInUser: false, }); ``` @@ -246,7 +246,7 @@ const clients = new Map(); function getClientForUser(userId: string, token: string): CopilotClient { if (!clients.has(userId)) { clients.set(userId, new CopilotClient({ - githubToken: token, + gitHubToken: token, useLoggedInUser: false, })); } diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-copilot-sdk.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-copilot-sdk.md index 3e4af8632131..78aa6a80ed9c 100644 --- a/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-copilot-sdk.md +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-copilot-sdk.md @@ -78,7 +78,7 @@ For Python and Go, which do not currently support passing extra CLI arguments, r ```typescript copy const client = new CopilotClient({ - githubToken: process.env.GITHUB_TOKEN, + gitHubToken: process.env.GITHUB_TOKEN, }); ``` diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/sdk-and-cli-compatibility.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/sdk-and-cli-compatibility.md index c83b556c9cbc..9970a992ebe5 100644 --- a/content/copilot/how-tos/copilot-sdk/troubleshooting/sdk-and-cli-compatibility.md +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/sdk-and-cli-compatibility.md @@ -61,7 +61,7 @@ contentType: how-tos | Create workspace file | `session.rpc.workspace.createFile()` | Create file in workspace | | **Authentication** | | | | Get auth status | `getAuthStatus()` | Check login state | -| Use token | `githubToken` option | Programmatic auth | +| Use token | `gitHubToken` option | Programmatic auth | | **Connectivity** | | | | Ping | `client.ping()` | Health check with server timestamp | | Get server status | `client.getStatus()` | Protocol version and server info | @@ -92,7 +92,9 @@ contentType: how-tos | **Experimental** | | | | Agent management | `session.rpc.agent.*` | List, select, deselect, get current agent | | Fleet mode | `session.rpc.fleet.start()` | Parallel sub-agent execution | -| Manual compaction | `session.rpc.compaction.compact()` | Trigger compaction on demand | +| Manual compaction | `session.rpc.history.compact()` | Trigger compaction on demand | +| History truncation | `session.rpc.history.truncate()` | Remove events from a point onward | +| Session forking | `server.rpc.sessions.fork()` | Fork a session at a point in history | ### Not available in SDK (CLI-only) @@ -228,7 +230,7 @@ const session = await client.createSession({ }); // Manual compaction (experimental) -const result = await session.rpc.compaction.compact(); +const result = await session.rpc.history.compact(); console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`); ``` diff --git a/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/agent-loop.md b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/agent-loop.md new file mode 100644 index 000000000000..02b8202855a3 --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/agent-loop.md @@ -0,0 +1,132 @@ +--- +title: Understanding the agent loop +shortTitle: Agent loop +intro: 'Learn how {% data variables.copilot.copilot_cli_short %} processes a user message end-to-end, from prompt to `session.idle`.' +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +category: + - Author and optimize with Copilot +--- + +{% data reusables.copilot.copilot-sdk.technical-preview-note %} + +## Architecture + +![Diagram showing the flow from your app to the SDK session, to the Copilot CLI, to the LLM, and back.](/assets/images/help/copilot/copilot-sdk/agent-loop-architecture.png) + +The **{% data variables.copilot.copilot_sdk_short %}** is a transport layer—it sends your prompt to **{% data variables.copilot.copilot_cli_short %}** over JSON-RPC and surfaces events back to your app. The **CLI** is the orchestrator that runs the agentic tool-use loop, making one or more LLM API calls until the task is done. + +## The tool-use loop + +When you call `session.send({ prompt })`, {% data variables.copilot.copilot_cli_short %} enters a loop: + +![Diagram of the tool-use loop: prompt to LLM call, tool execution if requested, otherwise session.idle.](/assets/images/help/copilot/copilot-sdk/agent-loop-tool-use-loop.png) + +The model sees the **full conversation history** on each call—system prompt, user message, and all prior tool calls and results. + +Each iteration of this loop is exactly one LLM API call, visible as one `assistant.turn_start` / `assistant.turn_end` pair in the event log. There are no hidden calls. + +## Turns + +A **turn** is a single LLM API call and its consequences: + +1. {% data variables.copilot.copilot_cli_short %} sends the conversation history to the LLM +1. The LLM responds (possibly with tool requests) +1. If tools were requested, {% data variables.copilot.copilot_cli_short %} executes them +1. `assistant.turn_end` is emitted + +A single user message typically results in **multiple turns**. For example, a question like "how does X work in this codebase?" might produce: + +| Turn | What the model does | toolRequests? | +|------|-------------------|---------------| +| 1 | Calls `grep` and `glob` to search the codebase | Yes | +| 2 | Reads specific files based on search results | Yes | +| 3 | Reads more files for deeper context | Yes | +| 4 | Produces the final text answer | No (loop ends) | + +The model decides on each turn whether to request more tools or produce a final answer. Each call sees the **full accumulated context** (all prior tool calls and results), so it can make an informed decision about whether it has enough information. + +## Event flow for a multi-turn interaction + +![Diagram of three turns in an agent interaction, each with start, message, tool, and end events, ending in session.idle.](/assets/images/help/copilot/copilot-sdk/agent-loop-event-flow.png) + +## Who triggers each turn + +| Actor | Responsibility | +|-------|---------------| +| **Your app** | Sends the initial prompt via `session.send()` | +| **{% data variables.copilot.copilot_cli_short %}** | Runs the tool-use loop—executes tools and feeds results back to the LLM for the next turn | +| **LLM** | Decides whether to request tools (continue looping) or produce a final response (stop) | +| **{% data variables.copilot.copilot_sdk_short %}** | Passes events through; does not control the loop | + +{% data variables.copilot.copilot_cli_short %} is purely mechanical: "model asked for tools → execute → call model again." The **model** is the decision-maker for when to stop. + +## `session.idle` vs `session.task_complete` + +These are two different completion signals with very different guarantees. + +### `session.idle` + +* **Always emitted** when the tool-use loop ends +* **Ephemeral**: not persisted to disk, not replayed on session resume +* **Means:** "the agent has stopped processing and is ready for the next message" +* **Use this** as your reliable "done" signal + +The {% data variables.copilot.copilot_sdk_short %}'s `sendAndWait()` method waits for this event: + +```typescript +// Blocks until session.idle fires +const response = await session.sendAndWait({ prompt: "Fix the bug" }); +``` + +### `session.task_complete` + +* **Optionally emitted**: requires the model to explicitly signal it +* **Persisted**: saved to the session event log on disk +* **Means:** "the agent considers the overall task fulfilled" +* Carries an optional `summary` field + +```typescript +session.on("session.task_complete", (event) => { + console.log("Task done:", event.data.summary); +}); +``` + +### Autopilot mode + +In **autopilot mode** (headless or autonomous operation), {% data variables.copilot.copilot_cli_short %} actively tracks whether the model has called `task_complete`. If the tool-use loop ends without it, {% data variables.copilot.copilot_cli_short %} injects a synthetic user message nudging the model to continue working. + +This creates a **two-level completion mechanism** in autopilot: + +1. The model calls `task_complete` with a summary → {% data variables.copilot.copilot_cli_short %} emits `session.task_complete` → done +1. The model stops without calling it → {% data variables.copilot.copilot_cli_short %} nudges → model continues or calls `task_complete` + +### Why `task_complete` might not appear + +In **interactive mode** (normal chat), {% data variables.copilot.copilot_cli_short %} does not nudge for `task_complete`. The model may skip it entirely. Common reasons: + +* **Conversational Q&A**: the model answers a question and simply stops—there's no discrete "task" to complete +* **Model discretion**: the model produces a final text response without calling the task-complete signal +* **Interrupted sessions**: the session ends before the model reaches a completion point + +{% data variables.copilot.copilot_cli_short %} emits `session.idle` regardless, because it's a mechanical signal (the loop ended), not a semantic one (the model thinks it's done). + +### Which signal to use + +| Use case | Signal | +|----------|--------| +| Wait for the agent to finish processing | `session.idle` | +| Know when a coding task is done | `session.task_complete` (best-effort) | +| Timeout and error handling | `session.idle` + `session.error` | + +## Counting LLM calls + +The number of `assistant.turn_start` / `assistant.turn_end` pairs in the event log equals the total number of LLM API calls made. There are no hidden calls for planning, evaluation, or completion checking. + +## Further reading + +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/streaming-events) +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/session-persistence) +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/working-with-hooks) diff --git a/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents.md b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents.md index 2ba0a2b84faa..5a92d54b1ac4 100644 --- a/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents.md +++ b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents.md @@ -59,13 +59,14 @@ For examples in Python, Go, and .NET, see the [`github/copilot-sdk` repository]( | Property | Type | Required | Description | |----------|------|----------|-------------| -| `name` | `string` | ✅ | Unique identifier for the agent | -| `displayName` | `string` | | Human-readable name shown in events | -| `description` | `string` | | What the agent does—helps the runtime select it | -| `tools` | `string[]` or `null` | | Names of tools the agent can use. `null` or omitted = all tools | -| `prompt` | `string` | ✅ | System prompt for the agent | -| `mcpServers` | `object` | | MCP server configurations specific to this agent | -| `infer` | `boolean` | | Whether the runtime can auto-select this agent (default: `true`) | +| `name` | `string` | Yes | Unique identifier for the agent | +| `displayName` | `string` | No | Human-readable name shown in events | +| `description` | `string` | No | What the agent does—helps the runtime select it | +| `tools` | `string[]` or `null` | No | Names of tools the agent can use. `null` or omitted = all tools | +| `prompt` | `string` | Yes | System prompt for the agent | +| `mcpServers` | `object` | No | MCP server configurations specific to this agent | +| `infer` | `boolean` | No | Whether the runtime can auto-select this agent (default: `true`) | +| `skills` | `string[]` | No | Skill names to preload into the agent's context at startup | > [!TIP] > A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities. @@ -76,6 +77,35 @@ In addition to per-agent configuration, you can set `agent` on the **session con |-------------------------|------|-------------| | `agent` | `string` | Name of the custom agent to pre-select at session creation. Must match a `name` in `customAgents`. | +## Per-agent skills + +You can preload skills into an agent's context using the `skills` property. When specified, the full content of each listed skill is eagerly injected into the agent's context at startup—the agent doesn't need to invoke a skill tool; the instructions are already present. Skills are opt-in: agents receive no skills by default, and sub-agents do not inherit skills from the parent. Skill names are resolved from the session-level `skillDirectories`. + +```typescript +const session = await client.createSession({ + skillDirectories: ["./skills"], + customAgents: [ + { + name: "security-auditor", + description: "Security-focused code reviewer", + prompt: "Focus on OWASP Top 10 vulnerabilities", + skills: ["security-scan", "dependency-check"], + }, + { + name: "docs-writer", + description: "Technical documentation writer", + prompt: "Write clear, concise documentation", + skills: ["markdown-lint"], + }, + ], + onPermissionRequest: async () => ({ kind: "approved" }), +}); +``` + +In this example, `security-auditor` starts with `security-scan` and `dependency-check` already injected into its context, while `docs-writer` starts with `markdown-lint`. An agent without a `skills` field receives no skill content. + +For examples in other languages, see the [`github/copilot-sdk` repository](https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md#per-agent-skills). {% data reusables.copilot.copilot-sdk.java-sdk-link %} + ## Selecting an agent at session creation You can pass `agent` in the session config to pre-select which custom agent should be active when the session starts. The value must match the `name` of one of the agents defined in `customAgents`. @@ -134,7 +164,7 @@ When a sub-agent runs, the parent session emits lifecycle events. Subscribe to t | `subagent.started` | Sub-agent begins execution | `toolCallId`, `agentName`, `agentDisplayName`, `agentDescription` | | `subagent.completed` | Sub-agent finishes successfully | `toolCallId`, `agentName`, `agentDisplayName` | | `subagent.failed` | Sub-agent encounters an error | `toolCallId`, `agentName`, `agentDisplayName`, `error` | -| `subagent.deselected` | Runtime switches away from the sub-agent | — | +| `subagent.deselected` | Runtime switches away from the sub-agent | None | ### Subscribing to events @@ -256,6 +286,73 @@ const session = await client.createSession({ > [!NOTE] > When `tools` is `null` or omitted, the agent inherits access to all tools configured on the session. Use explicit tool lists to enforce the principle of least privilege. +## Agent-exclusive tools + +Use the `defaultAgent` property on the session configuration to hide specific tools from the default agent (the built-in agent that handles turns when no custom agent is selected). This forces the main agent to delegate to sub-agents when those tools' capabilities are needed, keeping the main agent's context clean. + +This is useful when: + +* Certain tools generate large amounts of context that would overwhelm the main agent +* You want the main agent to act as an orchestrator, delegating heavy work to specialized sub-agents +* You need strict separation between orchestration and execution + +```typescript +import { CopilotClient, defineTool, approveAll } from "@github/copilot-sdk"; +import { z } from "zod"; + +const heavyContextTool = defineTool("analyze-codebase", { + description: "Performs deep analysis of the codebase, generating extensive context", + parameters: z.object({ query: z.string() }), + handler: async ({ query }) => { + // ... expensive analysis that returns lots of data + return { analysis: "..." }; + }, +}); + +const session = await client.createSession({ + tools: [heavyContextTool], + defaultAgent: { + excludedTools: ["analyze-codebase"], + }, + customAgents: [ + { + name: "researcher", + description: "Deep codebase analysis agent with access to heavy-context tools", + tools: ["analyze-codebase"], + prompt: "You perform thorough codebase analysis using the analyze-codebase tool.", + }, + ], +}); +``` + +For examples in Python, Go, and .NET, see the [`github/copilot-sdk` repository](https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md#agent-exclusive-tools). {% data reusables.copilot.copilot-sdk.java-sdk-link %} + +### How it works + +Tools listed in `defaultAgent.excludedTools`: + +1. **Are registered**—their handlers are available for execution +1. **Are hidden** from the main agent's tool list—the LLM won't see or call them directly +1. **Remain available** to any custom sub-agent that includes them in its `tools` array + +### Interaction with other tool filters + +`defaultAgent.excludedTools` is orthogonal to the session-level `availableTools` and `excludedTools`: + +| Filter | Scope | Effect | +|--------|-------|--------| +| `availableTools` | Session-wide | Allowlist—only these tools exist for anyone | +| `excludedTools` | Session-wide | Blocklist—these tools are blocked for everyone | +| `defaultAgent.excludedTools` | Main agent only | These tools are hidden from the main agent but available to sub-agents | + +Precedence: + +1. Session-level `availableTools`/`excludedTools` are applied first (globally) +1. `defaultAgent.excludedTools` is applied on top, further restricting the main agent only + +> [!NOTE] +> If a tool is in both `excludedTools` (session-level) and `defaultAgent.excludedTools`, the session-level exclusion takes precedence—the tool is unavailable to everyone. + ## Attaching MCP servers to agents Each custom agent can have its own MCP (Model Context Protocol) servers, giving it access to specialized data sources: diff --git a/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/index.md b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/index.md index 93c576597a29..8f74ad3ce376 100644 --- a/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/index.md +++ b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/index.md @@ -5,10 +5,12 @@ intro: Explore the capabilities you can add to your {% data variables.copilot.co versions: feature: copilot children: + - /agent-loop - /working-with-hooks - /custom-agents - /image-input - /mcp-servers + - /remote-sessions - /session-persistence - /custom-skills - /steering-and-queueing diff --git a/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/remote-sessions.md b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/remote-sessions.md new file mode 100644 index 000000000000..5b896c06043d --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/remote-sessions.md @@ -0,0 +1,70 @@ +--- +title: Remote sessions +shortTitle: Remote sessions +intro: 'Let users access their {% data variables.product.prodname_copilot_short %} session from {% data variables.product.github %} web and mobile by connecting the session to Mission Control.' +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +category: + - Author and optimize with Copilot +--- + +{% data reusables.copilot.copilot-sdk.technical-preview-note %} + +Remote sessions let users access their {% data variables.product.prodname_copilot_short %} session from {% data variables.product.github %} web and mobile. When enabled, the {% data variables.copilot.copilot_sdk_short %} connects each session to Mission Control, producing a URL that can be shared as a link or QR code. + +## Prerequisites + +* The user must be authenticated (GitHub token or logged-in user) +* The session's working directory must be a GitHub repository + +## Enabling remote sessions + +You can enable remote access at the client level (always-on) or toggle it per session (on-demand). + +### Always-on (client-level) + +Set `remote: true` when creating the client. Every session in a GitHub repo automatically gets a remote URL. + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient({ remote: true }); +const session = await client.createSession({ + workingDirectory: "/path/to/github-repo", + onPermissionRequest: async () => ({ allowed: true }), +}); + +session.on("session.info", (event) => { + if (event.data.infoType === "remote") { + console.log("Remote URL:", event.data.url); + } +}); +``` + +For examples in Python, Go, C#, and Rust, see the [`github/copilot-sdk` repository](https://github.com/github/copilot-sdk/blob/main/docs/features/remote-sessions.md#always-on-client-level). {% data reusables.copilot.copilot-sdk.java-sdk-link %} + +### On-demand (per-session toggle) + +Use `session.rpc.remote.enable()` to start remote access mid-session, and `session.rpc.remote.disable()` to stop it. This is equivalent to {% data variables.copilot.copilot_cli_short %}'s `/remote on` and `/remote off` commands. + +```typescript +const result = await session.rpc.remote.enable(); +console.log("Remote URL:", result.url); + +// Later: stop sharing +await session.rpc.remote.disable(); +``` + +For examples in Python, Go, C#, and Rust, see the [`github/copilot-sdk` repository](https://github.com/github/copilot-sdk/blob/main/docs/features/remote-sessions.md#on-demand-per-session-toggle). {% data reusables.copilot.copilot-sdk.java-sdk-link %} + +## QR code generation + +The remote URL can be rendered as a QR code for easy mobile access. The {% data variables.copilot.copilot_sdk_short %} provides the URL—use your preferred QR code library. + +## Notes + +* The `remote` client option only applies when the {% data variables.copilot.copilot_sdk_short %} spawns {% data variables.copilot.copilot_cli_short %}. It is ignored when connecting to an external server via `cliUrl`. +* If the working directory is not a GitHub repository, remote setup is silently skipped (always-on mode) or returns an error (on-demand mode). +* Remote sessions require authentication. Ensure `gitHubToken` or `useLoggedInUser` is configured. diff --git a/content/copilot/reference/ai-models/supported-models.md b/content/copilot/reference/ai-models/supported-models.md index 97a8262a4977..a788d32fe842 100644 --- a/content/copilot/reference/ai-models/supported-models.md +++ b/content/copilot/reference/ai-models/supported-models.md @@ -107,7 +107,7 @@ Some {% data variables.product.prodname_copilot_short %} models require minimum {% endrowheaders %} > [!NOTE] -> +> > * For {% data variables.copilot.copilot_gpt_53_codex %} in {% data variables.product.prodname_vscode %}, `v1.108` and later provide improved prompting and response quality. > * "No minimum listed" means the reviewed changelog or release guidance did not specify a minimum version, not that all older versions are supported. > * Even when a model appears in the model picker on older supported versions, prompting and model behavior may work best with the latest IDE and {% data variables.product.prodname_copilot_short %} extension or plugin versions. @@ -154,6 +154,12 @@ For more information about fallback and LTS models, see [AUTOTITLE](/copilot/con Evaluation models may be added, updated, or removed without notice. Availability and rate limits may differ from generally available models. +## Utility models + +Utility models power background features across surfaces, and cannot be disabled or selected in the model picker. See [AUTOTITLE](/copilot/concepts/models/utility-models). + +{% data reusables.copilot.utility-models %} + ## Next steps * For task-based guidance on selecting a model, see [AUTOTITLE](/copilot/reference/ai-models/model-comparison). diff --git a/content/get-started/using-github-docs/github-docs-api.md b/content/get-started/using-github-docs/github-docs-api.md new file mode 100644 index 000000000000..188d9c486871 --- /dev/null +++ b/content/get-started/using-github-docs/github-docs-api.md @@ -0,0 +1,112 @@ +--- +title: GitHub Docs API +intro: 'Use the official {% data variables.product.prodname_docs %} API to programmatically list pages, search, and retrieve {% data variables.product.company_short %} documentation content.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: GitHub Docs API +category: + - Explore GitHub plans and features +--- + + +{% data variables.product.prodname_docs %} provides several ways to access documentation content programmatically. You can retrieve individual articles as Markdown, list all available pages, search across the documentation, or point AI agents to the `llms.txt` file for content discovery. + +## Article endpoint + +The Article endpoint returns the Markdown content and metadata of any {% data variables.product.prodname_docs %} page. It supports all page types, including standard articles, REST API reference pages, GraphQL reference pages, and landing pages. + +The Article endpoint accepts the following query parameter: + +* `pathname` (required): The article path, including a language prefix such as `/en/` or `/ja/`. + * For example, `/en/get-started/start-your-journey/about-github-and-git`. + +In addition, `GET /api/article` and `GET /api/article/body` accept the following optional query parameter: + +* `apiVersion`: For REST API reference pages, specifies which API version to use. Defaults to the latest version. + +### Getting article content + +`GET https://docs.github.com/api/article/body` returns the full article content as Markdown. + +```shell +curl "https://docs.github.com/api/article/body?pathname=/en/get-started/start-your-journey/about-github-and-git" +``` + +To access a versioned article (for example, for {% data variables.product.prodname_ghe_cloud %}), include the version in the path: + +```shell +curl "https://docs.github.com/api/article/body?pathname=/en/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud" +``` + +### Getting article metadata + +`GET https://docs.github.com/api/article/meta` returns metadata about an article as JSON, including the title, intro, product area, document type, and breadcrumbs. + +```shell +curl "https://docs.github.com/api/article/meta?pathname=/en/get-started/start-your-journey/about-github-and-git" +``` + +### Getting content and metadata together + +`GET https://docs.github.com/api/article` returns both metadata and the article body in a single JSON response, combining the results of the body and meta endpoints. + +```shell +curl "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git" +``` + +## Pagelist endpoint + +The Pagelist endpoint returns a list of every available page path for a given language and documentation version. You can use it to discover all articles, then fetch individual articles with the Article endpoint. + +### Listing all pages + +`GET https://docs.github.com/api/pagelist/:lang/:version` returns a newline-separated list of all page paths for the specified language and version. + +```shell +curl "https://docs.github.com/api/pagelist/en/free-pro-team@latest" +``` + +#### Languages list + +`GET https://docs.github.com/api/pagelist/languages` returns all available language codes as JSON. Use this to find valid values for the `:lang` parameter above. + +#### Versions list + +`GET https://docs.github.com/api/pagelist/versions` returns all available documentation versions as JSON, including {% data variables.product.prodname_ghe_server %} version numbers. Use this to find valid values for the `:version` parameter above. + +## Search endpoint + +The Search endpoint lets you search across all {% data variables.product.prodname_docs %} content. It returns results sorted by relevance, with highlights and metadata for each matching page. + +### Searching docs content + +`GET https://docs.github.com/api/search/v1` accepts the following query parameters: + +* `query` (required): The search term. +* `client_name` (required for external clients such as `curl`): A name that identifies your client or integration. +* `version` (optional): The documentation version to search. Defaults to `free-pro-team`. Valid values include `free-pro-team`, `enterprise-cloud`, and {% data variables.product.prodname_ghe_server %} version numbers like `3.19`. +* `language` (optional): The language to search. Defaults to `en`. +* `page` (optional): The page number for paginated results. Defaults to `1`. +* `size` (optional): The number of results per page, up to a maximum of `50`. Defaults to `10`. + +```shell +curl "https://docs.github.com/api/search/v1?query=actions&client_name=docs-api-example&version=free-pro-team&language=en" +``` + +The response includes a `meta` object with information about the total number of matches and a `hits` array containing the matched pages with titles, URLs, breadcrumbs, and content highlights. + +## `llms.txt` for AI agents + +{% data variables.product.prodname_docs %} publishes an `llms.txt` file at `https://docs.github.com/llms.txt`, following the [`llms.txt` standard](https://llmstxt.org/). This file provides a structured overview of the documentation site designed for consumption by LLMs and AI-powered tools. + +If you are building an agent or tool that needs to access {% data variables.product.prodname_docs %}, `llms.txt` is the recommended starting point for discovering available content and API endpoints. + +{% ifversion fpt or ghec %} + +## Further reading + +* [AUTOTITLE](/copilot/how-tos/provide-context/use-mcp-in-your-ide/set-up-the-github-mcp-server) + +{% endif %} \ No newline at end of file diff --git a/content/get-started/using-github-docs/index.md b/content/get-started/using-github-docs/index.md index 94e2a949b772..f97cf5a2692c 100644 --- a/content/get-started/using-github-docs/index.md +++ b/content/get-started/using-github-docs/index.md @@ -8,4 +8,5 @@ versions: children: - /about-versions-of-github-docs - /using-hover-cards-on-github-docs + - /github-docs-api --- diff --git a/data/features/actions-github-token-pull-request-approval.yml b/data/features/actions-github-token-pull-request-approval.yml new file mode 100644 index 000000000000..6fe3c1626b8f --- /dev/null +++ b/data/features/actions-github-token-pull-request-approval.yml @@ -0,0 +1,7 @@ +# Approval-required workflow runs for pull requests created or updated by +# workflows using GITHUB_TOKEN. Implementation feature flag: +# `actions_requires_approval_for_actions_bot_prs`. +versions: + fpt: '*' + ghec: '*' + # ghes: '>=3.XX' # Uncomment when this ships to GHES (currently rolling out on dotcom) diff --git a/data/reusables/actions/actions-do-not-trigger-workflows.md b/data/reusables/actions/actions-do-not-trigger-workflows.md index 69e2400bd8ab..ba20bdcc672b 100644 --- a/data/reusables/actions/actions-do-not-trigger-workflows.md +++ b/data/reusables/actions/actions-do-not-trigger-workflows.md @@ -1,5 +1,6 @@ -When you use the repository's `GITHUB_TOKEN` to perform tasks, events triggered by the `GITHUB_TOKEN` will not create a new workflow run, with the following exception: +When you use the repository's `GITHUB_TOKEN` to perform tasks, events triggered by the `GITHUB_TOKEN` will not create a new workflow run, with the following exceptions: -* `workflow_dispatch` and `repository_dispatch` events always create workflow runs. +* `workflow_dispatch` and `repository_dispatch` events always create workflow runs.{% ifversion actions-github-token-pull-request-approval %} +* `pull_request` events with the `opened`, `synchronize`, or `reopened` activity types: when a workflow using `GITHUB_TOKEN` creates or updates a pull request, the resulting `pull_request` event creates workflow runs in an **approval-required** state. The pull request displays a banner in the merge box, and a user with write access to the repository can start the runs by selecting **Approve workflows to run**. Other `pull_request` activity types (such as `labeled`, `edited`, or `closed`) do not create workflow runs. This prevents recursive workflow runs while still allowing CI workflows to run on pull requests created by automation. For more information about approving workflow runs, see [AUTOTITLE](/actions/how-tos/manage-workflow-runs/approve-runs-from-forks).{% endif %} For all other events, this behavior prevents you from accidentally creating recursive workflow runs. For example, if a workflow run pushes code using the repository's `GITHUB_TOKEN`, a new workflow will not run even when the repository contains a workflow configured to run when `push` events occur. diff --git a/data/reusables/copilot/utility-models.md b/data/reusables/copilot/utility-models.md new file mode 100644 index 000000000000..ed799f88dfc4 --- /dev/null +++ b/data/reusables/copilot/utility-models.md @@ -0,0 +1,6 @@ +The following models are currently used as utility models: + +* {% data variables.copilot.copilot_gpt_4o_mini %} +* {% data variables.copilot.copilot_gpt_4o %} +* {% data variables.copilot.copilot_gpt_41 %} +* {% data variables.copilot.copilot_gpt_54_nano %}