Raise visibility to the requirement to use /agents for org/enterprise custom agents (#58301)

Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>
Co-authored-by: Sam Browning <106113886+sabrowning1@users.noreply.github.com>

Author: 3 people

content/copilot/concepts/agents/coding-agent/about-custom-agents.md

@@ -49,7 +49,7 @@ Focus on the following instructions:
 
 ## Where you can configure {% data variables.copilot.custom_agents_short %}
 
-You can define {% data variables.copilot.agent_profiles %} at the repository level (`.github/agents/CUSTOM-AGENT-NAME.md` in your repository) for project-specific agents, or at the organization or enterprise level for broader availability. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
+You can define {% data variables.copilot.agent_profiles %} at the repository level (`.github/agents/CUSTOM-AGENT-NAME.md` in your repository) for project-specific agents, or at the organization or enterprise level (`/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository) for broader availability. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
 
 ## Where you can use {% data variables.copilot.custom_agents_short %}
 

content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents.md

@@ -17,7 +17,9 @@ Enterprise-level {% data variables.copilot.custom_agents_short %} are defined in
 ## Creating a repository for your {% data variables.copilot.custom_agents_short %}
 
 1. Choose an organization in your enterprise to own the repository containing your enterprise-level {% data variables.copilot.custom_agents_short %}.
-1. Using the [{% data variables.copilot.custom_agents_short %} template repository](https://github.com/docs/custom-agents-template?ref_product=copilot&ref_type=engagement&ref_style=text&ref_plan=enterprise&utm_source=docs-web-custom-agents&utm_medium=docs&utm_campaign=universe25post), create a new **private** repository in your chosen organization named `.github-private`.
+1. Using the [{% data variables.copilot.custom_agents_short %} template repository](https://github.com/docs/custom-agents-template?ref_product=copilot&ref_type=engagement&ref_style=text&ref_plan=enterprise&utm_source=docs-web-custom-agents&utm_medium=docs&utm_campaign=universe25post), create a new repository in your chosen organization named `.github-private`. Set the visibility of the repository as follows:
+     * To grant **read access to all members** of your enterprise, choose {% octicon "organization" aria-hidden="true" aria-label="organization" %} **Internal**.
+     * To **manually grant access after creation**, choose {% octicon "lock" aria-hidden="true" aria-label="lock" %} **Private**.
 1. Update the template README as needed. Consider including creation guidelines for {% data variables.copilot.custom_agents_short %} or compliance considerations specific to your enterprise.
 
 ## Enabling and protecting {% data variables.copilot.custom_agents_short %} in your enterprise
@@ -35,4 +37,4 @@ Enterprise-level {% data variables.copilot.custom_agents_short %} are defined in
 
 To reduce your administrative burden and empower your SMEs, you can delegate the creation and management of {% data variables.copilot.custom_agents_short %} in your enterprise by creating a team of AI managers. See [AUTOTITLE](/copilot/tutorials/roll-out-at-scale/establish-ai-managers).
 
-If you prefer to maintain full control over your enterprise's tooling to ensure security and compliance, you can create and manage {% data variables.copilot.custom_agents_short %} yourself. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents).
+If you prefer to maintain full control over your enterprise's tooling to ensure security and compliance, you can create and manage {% data variables.copilot.custom_agents_short %} yourself. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/test-custom-agents).

content/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents.md

@@ -23,10 +23,13 @@ Before following this article, you should understand what {% data variables.copi
 
 1. Start creating your {% data variables.copilot.copilot_custom_agent_short %} repository using [{% data variables.product.github %}'s template repository](https://github.com/docs/custom-agents-template?ref_product=copilot&ref_type=engagement&ref_style=text&utm_source=docs-web-custom-agents&utm_medium=docs&utm_campaign=universe25post). The template repository contains a starter README and the necessary file structure to speed up your configuration.
 1. Select the **Choose an owner** {% octicon "triangle-down" aria-hidden="true" aria-label="triangle-down" %} dropdown menu, then click your organization.
-1. Name the repository `.github-private`, then write a brief description and set the visibility of the repository to private.
+1. Name the repository `.github-private`, then write a brief description.
+1. Select the visibility dropdown menu, then choose one of the following options:
+     * To grant **read access to all members** of your organization or enterprise, click {% octicon "organization" aria-hidden="true" aria-label="organization" %} **Internal**.
+     * To **manually grant access after creation**, or if internal visibility is not an option, click {% octicon "lock" aria-hidden="true" aria-label="lock" %} **Private**.
 {% data reusables.repositories.create-repo %}
 1. Update the template README as needed. Consider including creation guidelines for {% data variables.copilot.custom_agents_short %} or compliance considerations specific to your organization.
 
 ## Next steps
 
-To implement {% data variables.copilot.custom_agents_short %} in your organization, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents).
+To implement {% data variables.copilot.custom_agents_short %} in your organization, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/test-custom-agents).

content/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents.md

@@ -19,12 +19,13 @@ topics:
 1. Using the dropdown menu in the prompt box, select the repository you want to create the {% data variables.copilot.copilot_custom_agent_short %} profile in.
 
    > [!NOTE]
-   > Organization and enterprise owners can create organization and enterprise-level {% data variables.copilot.custom_agents_short %} that are available across all repositories within their organization or enterprise. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents).
+   > Organization and enterprise owners can create organization and enterprise-level {% data variables.copilot.custom_agents_short %} in a `.github-private` repository that are available across all repositories within their organization or enterprise. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents).
 
 1. Optionally, select the branch you want to create the {% data variables.copilot.agent_profile %} in. The default is the main branch.
-1. Click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %}, then click **{% octicon "plus" aria-label="Plus button" %} Create an agent**.
-1. An {% data variables.copilot.agent_profile %} template called `my-agent.md` will open in the `.github/agents` directory of the repository you chose. Edit the filename and configure the {% data variables.copilot.agent_profile %}, including the name, description, tools, and prompts. For more information on what the {% data variables.copilot.agent_profile %} can include, see the section below.
-1. Commit the file to the repository. Go back to the agents tab and refresh the page if needed. Your custom agent will now appear in the dropdown when you click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %} in the prompt box.
+1. Click {% octicon "copilot" aria-label="Select a custom agent" %}, then click **{% octicon "plus" aria-label="Plus button" %} Create an agent**. This will open a template agent profile called `my-agent.md` in the `.github/agents` directory of your target repository.
+1. If you are creating an organization or enterprise-level custom agent, delete the `.github/` portion of the file path to move your template to the root `agents` directory.
+1. Edit the filename and configure the {% data variables.copilot.agent_profile %}, including the name, description, tools, and prompts. For more information on what the {% data variables.copilot.agent_profile %} can include, see the section below.
+1. Commit the file to the repository and merge it into the default branch. Go back to the agents tab and refresh the page if needed. Your custom agent will now appear in the dropdown when you click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %} in the prompt box.
 
 ## Configuring an {% data variables.copilot.agent_profile %}
 

content/copilot/how-tos/use-copilot-agents/coding-agent/index.md

@@ -12,6 +12,7 @@ children:
   - /track-copilot-sessions
   - /review-copilot-prs
   - /create-custom-agents
+  - /test-custom-agents
   - /extend-coding-agent-with-mcp
   - /integrate-coding-agent-with-slack
   - /integrate-coding-agent-with-teams

content/copilot/how-tos/use-copilot-agents/coding-agent/test-custom-agents.md

@@ -0,0 +1,46 @@
+---
+title: Testing and releasing {% data variables.copilot.custom_agents_short %} in your organization or enterprise
+intro: 'Ensure your {% data variables.copilot.custom_agents_short %} are performant and compliant before releasing them to your company.'
+versions:
+  feature: copilot
+topics:
+  - Copilot
+shortTitle: Test custom agents
+contentType: how-tos
+---
+
+{% data reusables.copilot.custom-agents-preview-note %}
+
+## Introduction
+
+Before you release or update a {% data variables.copilot.copilot_custom_agent_short %} in your organization or enterprise, you can test the agent privately to ensure it meets your standards. Once you are satisfied, you can then easily change the location of your {% data variables.copilot.agent_profile %} to make it available across your company.
+
+## Prerequisites
+
+Before you can test a {% data variables.copilot.copilot_custom_agent_short %}, you need to set up your organization or enterprise for {% data variables.copilot.custom_agents_short %}. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) or [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
+
+## 1. Create your test {% data variables.copilot.copilot_custom_agent_short %}
+
+1. In your organization or enterprise's `.github-private` repository, create a new directory called `.github/agents`. Agents stored in this directory are only available to members of your organization or enterprise who have access to the `.github-private` repository, and can only be used when they start a task within that repository.
+1. In your `.github/agents` directory, create the {% data variables.copilot.agent_profile %} for your test agent. You can create a net-new profile or duplicate an existing profile to test potential updates. For information on configuring an {% data variables.copilot.agent_profile %}, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents#configuring-an-agent-profile).
+1. Merge your test {% data variables.copilot.agent_profile %} into the default branch of your repository.
+
+## 2. Test your {% data variables.copilot.copilot_custom_agent_short %}
+
+1. Navigate to the agents tab at [https://github.com/copilot/agents](https://github.com/copilot/agents?ref_product=copilot&ref_type=engagement&ref_style=text&utm_source=docs-signup-custom-agents&utm_medium=docs&utm_campaign=universe25post).
+1. Using the dropdown menu in the prompt box, select your `.github-private` repository.
+1. Select {% octicon "copilot" aria-label="Select a custom agent" %}, then click your test agent.
+1. To test your {% data variables.copilot.copilot_custom_agent_short %}, send {% data variables.product.prodname_copilot_short %} a prompt.
+1. In the "Recent sessions" section, click your session to see detailed information about your results.
+1. Continue making changes and testing your {% data variables.copilot.copilot_custom_agent_short %} as needed until you are satisfied with its performance.
+
+## 3. Release your {% data variables.copilot.copilot_custom_agent_short %}
+
+1. In your `.github-private` repository, move your {% data variables.copilot.agent_profile %} from the `.github/agents` directory into the `agents` directory.
+1. Merge your changes into the default branch. Your {% data variables.copilot.copilot_custom_agent_short %} is now available to all users in your organization or enterprise.
+
+## Next steps
+
+To monitor the usage of {% data variables.copilot.custom_agents_short %} in your organization, filter your organization's audit log by `actor:Copilot`. See [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization).
+
+To monitor the usage of {% data variables.copilot.custom_agents_short %} in your enterprise, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/monitor-agentic-activity).

content/copilot/how-tos/use-copilot-agents/use-copilot-cli.md

@@ -152,7 +152,7 @@ For more information, see [AUTOTITLE](/copilot/how-tos/configure-custom-instruct
 | --- | --- | --- |
 | User-level {% data variables.copilot.copilot_custom_agent_short %} | local `~/.copilot/agents` directory | All projects |
 | Repository-level {% data variables.copilot.copilot_custom_agent_short %} | `.github/agents` directory in your local and remote repositories | Current project |
-| Organization and Enterprise-level {% data variables.copilot.copilot_custom_agent_short %} | `.github/agents` directory in the `.github-private` repository in an organization or enterprise | All projects under your organization and enterprise account |
+| Organization and Enterprise-level {% data variables.copilot.copilot_custom_agent_short %} | `/agents` directory in the `.github-private` repository in an organization or enterprise | All projects under your organization and enterprise account |
 
 In the case of naming conflicts, a system-level agent overrides a repository-level agent, and the repository-level agent would override an organization-level agent.
 

content/copilot/tutorials/customization-library/custom-agents/your-first-custom-agent.md

@@ -76,7 +76,7 @@ Test this agent by giving it a task to complete:
 1. Using the dropdown menus in the text box, select the repository and branch you're comfortable testing with (ideally one with a minimal or outdated README).
 1. Click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %}, then click **{% octicon "plus" aria-label="Plus button" %} Create an agent**.
 1. An {% data variables.copilot.agent_profile %} template called `my-agent.md` will open in the `.github/agents` directory, in the repository you chose. Name the file `readme-specialist.md` and paste in the example {% data variables.copilot.agent_profile %}.
-1. Go back to the agents tab (you may need to refresh the page), and in the text box, select your "readme-specialist" agent from the dropdown.
+1. Commit and merge this file into your repository's default branch. Go back to the agents tab (you may need to refresh the page), and in the text box, select your "readme-specialist" agent from the dropdown.
 1. In the text box, enter a task for the agent (such as the example below) and click **{% octicon "paper-airplane" aria-label="Start task" %} Start task** or press <kbd>Return</kbd>.
 
    ```copilot copy

content/copilot/tutorials/roll-out-at-scale/establish-ai-managers.md

@@ -71,4 +71,4 @@ If you have created a ruleset targeting {% data variables.copilot.agent_profiles
 
 Now that you have established AI managers for your enterprise, help them customize and manage your enterprise's AI experience by sharing the following resources:
 * [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies)
-* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents)
+* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/test-custom-agents)