Create "Use Copilot agents" category under copilot-on-github (#60721)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jc-clark

content/copilot/how-tos/copilot-on-github/index.md

@@ -8,5 +8,6 @@ children:
   - /set-up-copilot
   - /chat-with-copilot
   - /copilot-for-github-tasks
+  - /use-copilot-agents
 contentType: how-tos
 ---

content/copilot/how-tos/copilot-on-github/use-copilot-agents/copilot-code-review.md

@@ -0,0 +1,70 @@
+---
+title: Using {% data variables.copilot.copilot_code-review %} on {% data variables.product.github %}
+shortTitle: '{% data variables.copilot.copilot_code-review_short %}'
+allowTitleToDifferFromFilename: true
+intro: '{% data variables.product.prodname_copilot %} reviews your pull requests and suggests ready-to-apply changes, so you get fast, actionable feedback on every commit.'
+versions:
+  feature: copilot
+contentType: how-tos
+category:
+  - Author and optimize with Copilot
+---
+
+{% data variables.copilot.copilot_code-review_short %} is also available for organization members without a {% data variables.product.prodname_copilot_short %} license, when enabled by an enterprise administrator or organization owner. See [{% data variables.copilot.copilot_code-review_short %} for organization members without a {% data variables.product.prodname_copilot_short %} license](/copilot/concepts/agents/code-review#copilot-code-review-for-organization-members-without-a-copilot-license).
+
+## Request a review from {% data variables.product.prodname_copilot_short %}
+
+1. On {% data variables.product.prodname_dotcom_the_website %}, create or open a pull request.
+1. Open the **Reviewers** menu, then select **{% data variables.product.prodname_copilot_short %}**.
+
+   ![Screenshot of selecting '{% data variables.product.prodname_copilot_short %}' from the 'Reviewers' menu.](/assets/images/help/copilot/code-review/request-review@2x.png)
+
+1. Wait for {% data variables.product.prodname_copilot_short %} to finish reviewing. This usually takes less than 30 seconds.
+
+1. Read through {% data variables.product.prodname_copilot_short %}'s comments on the pull request.
+
+   ![Screenshot of a code review left by {% data variables.product.prodname_copilot_short %}.](/assets/images/help/copilot/code-review/review-comment@2x.png)
+
+{% data variables.product.prodname_copilot_short %} always leaves a "Comment" review, not an "Approve" or "Request changes" review. Its reviews do not count toward required approvals and will not block merging.
+
+{% data variables.product.prodname_copilot_short %}'s review comments work like comments from human reviewers. Add reactions, reply, resolve, or hide them. Any replies you add are visible to other people but not to {% data variables.product.prodname_copilot_short %}.
+
+## Work with suggested changes
+
+{% data variables.product.prodname_copilot_short %}'s feedback often includes suggested changes you can apply in a few clicks. Accept a single suggestion or group multiple suggestions into one commit. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request).
+
+To have {% data variables.copilot.copilot_cloud_agent %} implement suggested changes directly:
+
+1. Opt into the {% data variables.release-phases.public_preview %} for {% data variables.copilot.copilot_code-review-tools_short %} and enable {% data variables.copilot.copilot_cloud_agent %}.
+1. On a review comment from {% data variables.copilot.copilot_code-review %}, click **Implement suggestion**. This creates a draft comment where you instruct {% data variables.product.prodname_copilot_short %} to address specific feedback. {% data variables.product.prodname_copilot_short %} then creates a new pull request against your branch with the suggestions applied.
+
+## Provide feedback on reviews
+
+Rate {% data variables.product.prodname_copilot_short %}'s comments to help improve future suggestions.
+
+1. On a review comment from {% data variables.product.prodname_copilot_short %}, click the thumbs up (:+1:) or thumbs down (:-1:) button.
+
+   ![Screenshot showing a {% data variables.copilot.copilot_code-review_short %} comment with the thumbs up and thumbs down buttons.](/assets/images/help/copilot/code-review/feedback-controls@2x.png)
+
+1. If you click thumbs down, optionally pick a reason and leave a comment, then click **Submit feedback**.
+
+   ![Screenshot of the form for providing additional information when you give negative feedback on a comment from {% data variables.product.prodname_copilot_short %}.](/assets/images/help/copilot/code-review/feedback-modal@2x.png)
+
+## Request a re-review
+
+{% data variables.product.prodname_copilot_short %} does not automatically re-review when you push new changes. To request a re-review, click the {% octicon "sync" aria-label="Re-request review" %} button next to {% data variables.product.prodname_copilot_short %}'s name in the **Reviewers** menu.
+
+When re-reviewing, {% data variables.product.prodname_copilot_short %} may repeat previous comments, even if you resolved or downvoted them.
+
+## Enable automatic reviews
+
+By default, you request reviews from {% data variables.product.prodname_copilot_short %} manually on each pull request. To enable automatic reviews for all pull requests, see [AUTOTITLE](/copilot/how-tos/agents/copilot-code-review/automatic-code-review).
+
+## Customize reviews with custom instructions
+
+{% data reusables.copilot.code-review.custom-instructions-information %}
+
+## Further reading
+
+* [AUTOTITLE](/copilot/concepts/code-review)
+* [AUTOTITLE](/copilot/how-tos/copilot-on-github/use-copilot-agents/review-copilot-output)

content/copilot/how-tos/copilot-on-github/use-copilot-agents/index.md

@@ -0,0 +1,15 @@
+---
+title: 'Use {% data variables.product.prodname_copilot_short %} agents'
+shortTitle: 'Use {% data variables.product.prodname_copilot_short %} agents'
+intro: 'Delegate tasks to {% data variables.product.prodname_copilot %} agents on {% data variables.product.github %}, track their progress, and review the results.'
+versions:
+  feature: copilot
+children:
+  - /overview
+  - /kick-off-a-task
+  - /research-plan-iterate
+  - /manage-and-track-agents
+  - /copilot-code-review
+  - /review-copilot-output
+contentType: how-tos
+---

content/copilot/how-tos/copilot-on-github/use-copilot-agents/kick-off-a-task.md

@@ -0,0 +1,53 @@
+---
+title: Kick off a task with {% data variables.product.prodname_copilot_short %} agents on {% data variables.product.github %}
+shortTitle: Kick off a task
+intro: 'Decide whether {% data variables.copilot.copilot_cloud_agent %} creates a pull request immediately or works on a branch you review and iterate on first.'
+product: '{% data reusables.gated-features.copilot-cloud-agent %}<br><a href="https://github.com/features/copilot/plans?ref_product=copilot&ref_type=purchase&ref_style=button" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Sign up for {% data variables.product.prodname_copilot_short %}</span> {% octicon "link-external" height:16 %}</a>'
+versions:
+  feature: copilot
+contentType: how-tos
+category:
+  - Author and optimize with Copilot
+---
+
+You can start a {% data variables.copilot.copilot_cloud_agent %} task in several ways. **Assigning an issue** always creates a pull request. **Starting with a prompt** works on a branch by default, giving you a chance to review, steer, and iterate before you open a pull request. **Seeding a repository** creates a draft pull request with scaffolded code.
+
+## Assign an issue to {% data variables.product.prodname_copilot_short %}
+
+Assigning an issue always creates a pull request. {% data variables.product.prodname_copilot_short %} works on the task and requests your review when it finishes.
+
+1. In the right sidebar of the issue, click **Assignees**.
+1. Click **Copilot** from the assignees list.
+1. Optionally, add context in the **Optional prompt** field—for example, coding patterns, files to modify, or testing requirements.
+1. Optionally, change the target repository or base branch using the dropdown menus.
+
+{% data reusables.copilot.optional-select-custom-agent-dotcom %}
+{% data reusables.copilot.optional-select-copilot-cloud-agent-model %}
+
+{% data variables.product.prodname_copilot_short %} receives the issue title, description, and existing comments at assignment time. It does not see comments added after assignment, so post follow-up information on the pull request instead.
+
+## Start a task with a prompt
+
+{% data variables.copilot.copilot_cloud_agent_short_cap_c %} works on a branch by default. You can review the diff, iterate with follow-up prompts, and create a pull request when you're ready.
+
+{% data reusables.copilot.open-agents-panel-or-page %}
+{% data reusables.copilot.cloud-agent.new-agent-task-form-instructions %}
+
+The same prompt box is available on your [dashboard](https://github.com) and in {% data variables.copilot.copilot_chat_short %} (type `/task`).
+
+For the full workflow of researching, planning, and iterating before creating a pull request, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/use-copilot-agents/research-plan-iterate).
+
+## Seed a new repository
+
+When you create a new repository, you can have {% data variables.product.prodname_copilot_short %} generate starter code.
+
+{% data reusables.repositories.create_new %}
+1. In the **Prompt** field, describe what you want {% data variables.product.prodname_copilot_short %} to build — for example, `Create a Rust CLI for converting CSV spreadsheets to Markdown`.
+{% data reusables.repositories.create-repo %}
+
+{% data variables.product.prodname_copilot_short %} opens a draft pull request with the scaffolded code.
+
+## Further reading
+
+* [AUTOTITLE](/copilot/tutorials/cloud-agent/get-the-best-results)
+* [AUTOTITLE](/copilot/how-tos/copilot-on-github/use-copilot-agents/manage-and-track-agents)

content/copilot/how-tos/copilot-on-github/use-copilot-agents/manage-and-track-agents.md

@@ -0,0 +1,60 @@
+---
+title: Manage and track {% data variables.copilot.copilot_cloud_agent %} sessions
+shortTitle: Manage and track agents
+intro: 'Monitor your agent''s progress in real time, steer it with follow-up prompts, and stop or archive sessions.'
+product: '{% data reusables.gated-features.copilot-cloud-agent %}<br><a href="https://github.com/features/copilot/plans?ref_product=copilot&ref_type=purchase&ref_style=button" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Sign up for {% data variables.product.prodname_copilot_short %}</span> {% octicon "link-external" height:16 %}</a>'
+versions:
+  feature: copilot
+contentType: how-tos
+category:
+  - Author and optimize with Copilot
+redirect_from:
+  - /copilot/how-tos/use-copilot-agents/manage-agents
+---
+
+Use the agents panel on {% data variables.product.github %} to start, monitor, and manage agent sessions across your repositories.
+
+## Monitor agent activity
+
+Track sessions from the agents panel (available from any page on {% data variables.product.github %}) or from the [agents page](https://github.com/copilot/agents?ref_product=copilot&ref_type=engagement&ref_style=text). Sessions that you started, or that another user prompted {% data variables.product.prodname_copilot_short %} to work on, appear in your sessions list.
+
+Click a session to open the session log and overview, where you can monitor the agent's progress, token usage, and session length.
+
+## Review session logs
+
+Session logs show {% data variables.product.prodname_copilot_short %}'s internal reasoning and the tools it used to understand your repository, make changes, and validate its work. {% data variables.product.prodname_copilot_short %} has its own ephemeral development environment, so it can run automated tests and linters to validate changes before pushing.
+
+## Trace commits to session logs
+
+Commits from {% data variables.copilot.copilot_cloud_agent %} are authored by {% data variables.product.prodname_copilot_short %}, with the person who started the task listed as co-author. Each commit message includes a link to the session logs, so you can trace why a change was made during code review or an audit. Commits are signed and appear as "Verified" on {% data variables.product.github %}.
+
+## Steer an agent session
+
+If {% data variables.product.prodname_copilot_short %} is heading in the wrong direction, or you realize your original prompt needs adjusting, you can redirect it without stopping the session.
+
+1. Open the [agents page](https://github.com/copilot/agents?ref_product=copilot&ref_type=engagement&ref_style=text) and select the session.
+1. In the prompt box below the session log, type your follow-up. For example:
+
+   ```text
+   Use our existing ErrorHandler utility class instead of writing custom try-catch blocks for each endpoint.
+   ```
+
+1. Press <kbd>Enter</kbd>. {% data variables.product.prodname_copilot_short %} implements your input after it finishes its current tool call.
+
+Each steering message uses **one premium request**. Steering is not available for third-party coding agents.
+
+## Stop a session
+
+If the task no longer needs to be done, or you want to start over with a new prompt, click **Stop session** in the session log viewer. Stopping a session ends the {% data variables.product.prodname_actions %} run and preserves any commits already pushed.
+
+## Archive sessions
+
+Archive stopped sessions to remove them from your sessions list.
+
+1. Open the stopped session.
+1. Click **{% octicon "kebab-horizontal" aria-label="More actions" %}**, then click **{% octicon "inbox" aria-hidden="true" aria-label="inbox" %} Archive session**.
+1. In the dialog, click **Yes, archive**.
+
+## Further reading
+
+* [AUTOTITLE](/copilot/tutorials/cloud-agent/get-the-best-results)

content/copilot/how-tos/copilot-on-github/use-copilot-agents/overview.md

@@ -0,0 +1,74 @@
+---
+title: Get started with {% data variables.product.prodname_copilot_short %} agents on {% data variables.product.github %}
+shortTitle: Get started
+intro: Try {% data variables.copilot.copilot_cloud_agent %} end-to-end in about ten minutes.
+product: '{% data reusables.gated-features.copilot-cloud-agent %}<br><a href="https://github.com/features/copilot/plans?ref_product=copilot&ref_type=purchase&ref_style=button" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Sign up for {% data variables.product.prodname_copilot_short %}</span> {% octicon "link-external" height:16 %}</a>'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: copilot
+contentType: how-tos
+---
+
+## Prerequisite
+
+You need a repository where {% data variables.copilot.copilot_cloud_agent %} is enabled. For {% data variables.copilot.copilot_business_short %} and {% data variables.copilot.copilot_enterprise_short %} subscribers, an administrator must enable the agent before you can use it. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/access-management).
+
+## Step 1: Assign an issue to {% data variables.product.prodname_copilot_short %}
+
+Pick a repository where {% data variables.copilot.copilot_cloud_agent %} is enabled and find an open issue—or create a small one, such as "Add a CONTRIBUTING.md file."
+
+1. In the right sidebar, click **Assignees**, then select **Copilot**.
+1. Optionally, add instructions in the **Optional prompt** field.
+
+    For example: `Keep the file short and include a code of conduct section.`
+1. Click **Assign**.
+
+{% data variables.product.prodname_copilot_short %} starts a session and begins working on a pull request.
+
+## Step 2: Start a research task at the same time
+
+While {% data variables.product.prodname_copilot_short %} works on the issue, start a second, non-coding task to see two sessions running in parallel.
+
+1. In the same repository, click the **{% octicon "agent" aria-hidden="true" aria-label="agent" %} Agents** tab.
+1. Type a research prompt. 
+    
+    For example: `Investigate which dependencies in this repo are outdated and summarize what upgrading would involve.`
+1. Click **{% octicon "paper-airplane" aria-label="Start task" %}** or press <kbd>Enter</kbd>.
+
+A second session appears in the panel alongside the first.
+
+## Step 3: Watch both sessions
+
+Both sessions update in real time. Click either session to view the agent's reasoning, the files it reads, and the changes it makes.
+
+While a session is running, type in the prompt box below the log to steer the agent.
+
+For example: `Focus on security-related dependencies first.`
+
+For more details on monitoring, steering, and stopping sessions, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/use-copilot-agents/manage-and-track-agents).
+
+## Step 4: Request a {% data variables.copilot.copilot_code-review_short %} on the pull request
+
+When the coding task finishes, {% data variables.product.prodname_copilot_short %} opens a pull request and adds you as a reviewer.
+
+1. Open the pull request from the notification or from the session log.
+1. In the right sidebar, click **Reviewers**, then select **{% data variables.product.prodname_copilot_short %}**.
+1. Wait for {% data variables.copilot.copilot_code-review_short %} to leave comments—usually under 30 seconds.
+
+Read through the review comments. {% data variables.product.prodname_copilot_short %} may suggest changes you can apply directly with a click.
+
+For the full set of code-review options, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/use-copilot-agents/copilot-code-review).
+
+## Step 5: Review the output and iterate
+
+Now review the code changes yourself, just as you would for any contributor's pull request.
+
+* **Request changes from {% data variables.product.prodname_copilot_short %}** — mention `@copilot` in a comment describing what to fix. {% data variables.product.prodname_copilot_short %} pushes new commits to the same branch.
+* **Make changes yourself** — check out the branch and push your own commits.
+* **Approve and merge** — when you're satisfied, merge the pull request.
+
+For more on reviewing {% data variables.product.prodname_copilot_short %}'s work, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/use-copilot-agents/review-copilot-output).
+
+## Next steps
+
+* [AUTOTITLE](/copilot/tutorials/cloud-agent/get-the-best-results) — Write effective prompts and get the most out of agents.