Add a quickstart article for GitHub Copilot Extensions (#52544)
Co-authored-by: Dimitrios Philliou <d1m1tr10s@github.com> Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com> Co-authored-by: Jules <19994093+jules-p@users.noreply.github.com>
This commit is contained in:
Sam Browning
@@ -8,7 +8,6 @@ topics:
|
||||
- Copilot
|
||||
children:
|
||||
- /about-copilot-agents
|
||||
- /using-a-demo-agent
|
||||
- /configuring-your-copilot-agent-to-communicate-with-the-copilot-platform
|
||||
- /configuring-your-copilot-agent-to-communicate-with-github
|
||||
- /using-copilots-llm-for-your-agent
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: Using a demo agent
|
||||
intro: 'Learn about how you can use a demo agent to explore how {% data variables.product.prodname_copilot_extensions_short %} work.'
|
||||
versions:
|
||||
feature: copilot-extensions
|
||||
topics:
|
||||
- Copilot
|
||||
shortTitle: Using a demo agent
|
||||
type: how_to
|
||||
---
|
||||
|
||||
{% data reusables.copilot.copilot-extensions.beta-note %}
|
||||
|
||||
## About demo agents
|
||||
|
||||
If you're not ready to build your own {% data variables.product.prodname_copilot_agent_short %} from scratch, you can clone and use a demo agent to experiment with {% data variables.product.prodname_copilot_extensions %}. You can use the demo agent as a basis for your own agent, or you can use it to familiarize yourself with the {% data variables.product.prodname_copilot_extensions_short %} development and deployment process.
|
||||
|
||||
{% data variables.product.company_short %} provides a few different demo agents that you can use. You can find them in the [copilot-extensions](https://github.com/copilot-extensions) organization.
|
||||
|
||||
This article provides instructions for running the Blackbeard demo agent on your local machine, but should be similar for other demo agents.
|
||||
|
||||
1. Clone the repository. Run the following command in your terminal (Mac or Linux) or Git Bash (Windows):
|
||||
|
||||
```shell copy
|
||||
git clone https://github.com/copilot-extensions/blackbeard-extension.git
|
||||
```
|
||||
|
||||
1. Open the agent repository locally by running the following command in your terminal (Mac or Linux) or Git Bash (Windows):
|
||||
|
||||
```shell copy
|
||||
cd blackbeard-extension
|
||||
```
|
||||
|
||||
1. To install the necessary dependencies, run the following command in your terminal (Mac or Linux) or Git Bash (Windows):
|
||||
|
||||
```shell copy
|
||||
npm install
|
||||
```
|
||||
|
||||
1. To start your server, run the following command in your terminal (Mac or Linux) or Git Bash (Windows):
|
||||
|
||||
```shell copy
|
||||
npm start
|
||||
```
|
||||
|
||||
> [!NOTE] Keep the terminal window open while you are using your agent.
|
||||
|
||||
## Next steps
|
||||
|
||||
* [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent)
|
||||
@@ -1,47 +1,47 @@
|
||||
---
|
||||
title: Configuring your server to deploy your Copilot agent
|
||||
intro: 'Learn how to deploy your {% data variables.product.prodname_copilot_short %} agent to a server that is accessible to the internet.'
|
||||
title: Configuring your server to host your Copilot agent
|
||||
intro: 'Learn how to make your {% data variables.product.prodname_copilot_short %} agent accessible to the internet.'
|
||||
versions:
|
||||
feature: copilot-extensions
|
||||
redirect_from:
|
||||
- /copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent
|
||||
topics:
|
||||
- Copilot
|
||||
shortTitle: Deploy your agent
|
||||
shortTitle: Host your agent
|
||||
type: how_to
|
||||
---
|
||||
|
||||
{% data reusables.copilot.copilot-extensions.beta-note %}
|
||||
|
||||
Your {% data variables.product.prodname_copilot_agent_short %} must be hosted on a server that is accessible to the internet. This guide will help you set up a server to run your {% data variables.product.prodname_copilot_agent_short %}. In this guide, we will use [ngrok](https://ngrok.com/) to create a tunnel to your local server, but you could also use a service like [localtunnel](https://localtunnel.github.io/www/) or [serveo](https://serveo.net/).
|
||||
Your {% data variables.product.prodname_copilot_agent_short %} must be hosted on a server that is accessible to the internet. In this guide, we will use [ngrok](https://ngrok.com/) to create a tunnel to your local server, but you could also use a service like [localtunnel](https://localtunnel.github.io/www/) or [serveo](https://serveo.net/).
|
||||
|
||||
Alternatively, if you are a {% data variables.product.prodname_codespaces %} user, you can use the built-in {% data variables.product.prodname_codespaces %} port forwarding. For more information, see "[AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace)."
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* You have created a {% data variables.product.prodname_copilot_agent_short %}. For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension)." Alternatively, you can use a demo agent. For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-a-demo-agent)."
|
||||
* You have created a {% data variables.product.prodname_copilot_agent_short %}. For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension)."
|
||||
|
||||
## Configuring your server
|
||||
|
||||
1. Visit the [ngrok setup & installation page](https://dashboard.ngrok.com/get-started/setup/).
|
||||
1. Visit the [ngrok setup & installation page](https://dashboard.ngrok.com/get-started/setup/).
|
||||
1. If you do not yet have an account, follow the instructions on screen to sign up.
|
||||
1. Under "Agents," ensure the correct operating system is selected.
|
||||
1. Under "Installation," follow the instructions for your operating system to download and install ngrok.
|
||||
1. Under "Deploy your app online," selection **Ephemeral domain** or **Static domain**.
|
||||
1. Under "Deploy your app online," select **Ephemeral domain** or **Static domain**.
|
||||
1. Run the command provided in your terminal, replacing the port number with the port your agent is configured to run on. For example:
|
||||
|
||||
* For an ephemeral domain:
|
||||
|
||||
```shell copy
|
||||
ngrok http http://localhost:3000
|
||||
ngrok http http://localhost:AGENT-PORT-NUMBER
|
||||
```
|
||||
|
||||
* For a static domain:
|
||||
|
||||
```shell copy
|
||||
ngrok http --domain=YOUR-STATIC-DOMAIN.ngrok-free.app 3000
|
||||
ngrok http --domain=YOUR-STATIC-DOMAIN.ngrok-free.app AGENT-PORT-NUMBER
|
||||
```
|
||||
|
||||
> [!NOTE] The Blackbeard demo extension is configured to run on port 3000 by default.
|
||||
|
||||
1. In your terminal, next to "Forwarding," copy the URL that ngrok has assigned to your server. You will need this forwarding endpoint when you are configuring your {% data variables.product.prodname_github_app %}.
|
||||
|
||||
> [!NOTE] Do not copy the `-> http://localhost:XXXX` part of the URL.
|
||||
@@ -15,7 +15,7 @@ A {% data variables.product.prodname_copilot_extension_short %} is a {% data var
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* You have created a {% data variables.product.prodname_copilot_agent_short %}. For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension)." Alternatively, you can use a demo agent. For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-a-demo-agent)."
|
||||
* You have created a {% data variables.product.prodname_copilot_agent_short %}. For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension)."
|
||||
* You have configured your server to deploy your {% data variables.product.prodname_copilot_agent_short %}, and you have your hostname (aka forwarding endpoint). For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent)."
|
||||
|
||||
## Creating a {% data variables.product.prodname_github_app %}
|
||||
|
||||
@@ -7,7 +7,7 @@ versions:
|
||||
topics:
|
||||
- Copilot
|
||||
children:
|
||||
- /configuring-your-server-to-deploy-your-copilot-agent
|
||||
- /configuring-your-server-to-host-your-copilot-agent
|
||||
- /creating-a-github-app-for-your-copilot-extension
|
||||
- /configuring-your-github-app-for-your-copilot-agent
|
||||
---
|
||||
|
||||
@@ -8,6 +8,7 @@ topics:
|
||||
- Copilot
|
||||
children:
|
||||
- /about-building-copilot-extensions
|
||||
- /quickstart-for-github-copilot-extensions
|
||||
- /setting-up-copilot-extensions
|
||||
- /building-a-copilot-agent-for-your-copilot-extension
|
||||
- /creating-a-copilot-extension
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
title: Quickstart for GitHub Copilot Extensions
|
||||
defaultTool: vscode
|
||||
intro: 'Build and try out {% data variables.product.github %}''s Blackbeard extension to learn about the development process for {% data variables.product.prodname_copilot_extensions %}.'
|
||||
versions:
|
||||
feature: copilot-extensions
|
||||
redirect_from:
|
||||
- /copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-a-demo-agent
|
||||
topics:
|
||||
- Copilot
|
||||
shortTitle: Extensions quickstart
|
||||
---
|
||||
|
||||
{% data reusables.copilot.copilot-extensions.beta-note %}
|
||||
|
||||
The [Blackbeard extension](https://github.com/copilot-extensions/blackbeard-extension) is a {% data variables.product.prodname_copilot_extension %} built with a simple agent that responds to requests like a pirate using {% data variables.product.prodname_copilot_short %}'s large language model (LLM) API and special system prompts.
|
||||
|
||||
This quickstart is designed to help you build and chat with the Blackbeard extension as quickly as possible. To instead learn how to create a new {% data variables.product.prodname_copilot_extension %}, see "[AUTOTITLE](/copilot/building-copilot-extensions/setting-up-copilot-extensions)."
|
||||
|
||||
## 1. Create and install a {% data variables.product.prodname_github_app %}
|
||||
|
||||
In the developer settings for your {% data variables.product.github %} account, create a {% data variables.product.prodname_github_app %}. Your {% data variables.product.prodname_github_app %} must have:
|
||||
* A name
|
||||
* A homepage URL
|
||||
* Webhooks deselected
|
||||
|
||||
After you create your app, click **Install App** in the sidebar, then install your app on your account.
|
||||
|
||||
For detailed instructions, see "[AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension#creating-a-github-app)."
|
||||
|
||||
{% vscode %}
|
||||
|
||||
## 2. Clone and host the Blackbeard agent locally
|
||||
|
||||
Rather than deploying the Blackbeard agent as a web app, you can host your agent locally for a significantly faster build process.
|
||||
|
||||
1. Using the Terminal built into {% data variables.product.prodname_vscode_shortname %}, clone the [`copilot-extensions/blackbeard-extension`](https://github.com/copilot-extensions/blackbeard-extension) repository.
|
||||
1. In the same Terminal, run `npm install` to install the necessary dependencies, then run `npm start` to start the Blackbeard agent on port 3000.
|
||||
1. In the "Ports" tab of the {% data variables.product.prodname_vscode_shortname %} panel, click **Forward a port** or **Add port**, then add port 3000.
|
||||
1. Right-click the port and set the visibility to "Public," then copy the local address.
|
||||
|
||||
## 3. Integrate and test the Blackbeard extension
|
||||
|
||||
After you set up your {% data variables.product.prodname_github_app %} and Blackbeard agent, you can integrate the agent with your app and test the Blackbeard extension. You need to make the following changes to your {% data variables.product.prodname_github_app %} settings:
|
||||
* In the "General" settings, in the "Callback URL" field, paste the local address for your agent.
|
||||
* In the "Permissions & events" settings, grant read-only permissions to {% data variables.product.prodname_copilot_chat_short %}.
|
||||
* In the "{% data variables.product.prodname_copilot_short %}" settings, set your app type to "Agent," then fill out the remaining fields.
|
||||
|
||||
After you update your {% data variables.product.prodname_github_app %} settings, you can start chatting with your extension by typing `@YOUR-EXTENSION-NAME` in the {% data variables.product.prodname_copilot_chat_short %} window, then sending a prompt as normal.
|
||||
|
||||
For more detailed instructions, see "[AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent#configuring-your-github-app)."
|
||||
|
||||
{% endvscode %}
|
||||
|
||||
{% codespaces %}
|
||||
|
||||
## 2. Clone and host the Blackbeard agent in a codespace
|
||||
|
||||
Rather than deploying the Blackbeard agent as a web app, you can host your agent in a codespace for a significantly faster build process.
|
||||
|
||||
1. Navigate to the [`copilot-extensions/blackbeard-extension`](https://github.com/copilot-extensions/blackbeard-extension) repository. Select the {% octicon "code" aria-hidden="true" %} **Code** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Create codespace on main**.
|
||||
1. To find your new codespace, select the {% octicon "code" aria-hidden="true" %} **Code** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu. Next to your new codespace, select {% octicon "kebab-horizontal" aria-label="Show more actions for codespace" %}, then click {% octicon "globe" aria-hidden="true" %} **Open in Browser**.
|
||||
1. In the integrated Terminal, run `npm start` to start the Blackbeard agent on port 3000.
|
||||
1. In the "Ports" tab of the {% data variables.product.prodname_vscode_shortname %} panel, click **Forward a port**, then add port 3000.
|
||||
1. Right-click the port and set the visibility to "Public," then copy the local address.
|
||||
|
||||
## 3. Integrate and test the Blackbeard extension
|
||||
|
||||
After you set up your {% data variables.product.prodname_github_app %} and Blackbeard agent, you can integrate the agent with your app and test the Blackbeard extension. You need to make the following changes to your {% data variables.product.prodname_github_app %} settings:
|
||||
* In the "General" settings, in the "Callback URL" field, paste the forwarded address for your agent.
|
||||
* In the "Permissions & events" settings, grant read-only permissions to {% data variables.product.prodname_copilot_chat_short %}.
|
||||
* In the "{% data variables.product.prodname_copilot_short %}" settings, set your app type to "Agent," then fill out the remaining fields.
|
||||
|
||||
After you update your {% data variables.product.prodname_github_app %} settings, you can start chatting with your extension by typing `@YOUR-EXTENSION-NAME` in the {% data variables.product.prodname_copilot_chat_short %} window of a supported client or IDE, then sending a prompt as normal. For a list of supported clients and IDEs, see "[AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions#supported-clients-and-ides)."
|
||||
|
||||
> [!NOTE] Chatting with {% data variables.product.prodname_copilot_extensions %} in {% data variables.product.prodname_github_codespaces %} is not supported.
|
||||
|
||||
For more detailed instructions, see "[AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent#configuring-your-github-app)."
|
||||
|
||||
{% endcodespaces %}
|
||||
|
||||
{% bash %}
|
||||
|
||||
## 2. Clone and start the Blackbeard agent locally
|
||||
|
||||
Rather than deploying the Blackbeard agent as a web app, you can host your agent locally for a significantly faster build process.
|
||||
|
||||
1. Using your command line application, clone the [`copilot-extensions/blackbeard-extension`](https://github.com/copilot-extensions/blackbeard-extension) repository.
|
||||
1. Run `npm install` to install the necessary dependencies, then run `npm start` to start the Blackbeard agent on port 3000.
|
||||
|
||||
## 3. Expose your local server
|
||||
|
||||
To make the Blackbeard agent accessible to the {% data variables.product.prodname_copilot_short %} platform and {% data variables.product.github %}, you need to expose your local server so it's reachable by HTTP requests. You can use any port forwarding or tunneling service to achieve this. For the following steps, we'll use ngrok.
|
||||
|
||||
1. Navigate to [ngrok's download page](https://ngrok.com/download), then install the appropriate version of ngrok for your operating system.
|
||||
1. Navigate to the [ngrok setup and installation page](https://dashboard.ngrok.com/get-started/setup/), then log in or sign up for an ngrok account.
|
||||
1. To expose your local server, in a new window of your command line application, run the following command:
|
||||
|
||||
```shell copy
|
||||
ngrok http http://localhost:3000
|
||||
```
|
||||
|
||||
1. In your command line application, next to "Forwarding," copy the URL that ngrok assigned to your server.
|
||||
|
||||
## 4. Integrate and test the Blackbeard extension
|
||||
|
||||
To integrate your {% data variables.product.prodname_github_app %} with the Blackbeard agent, you need to make the following changes to your app settings:
|
||||
* In the "General" settings, in the "Callback URL" field, paste the URL for your exposed server.
|
||||
* In the "Permissions & events" settings, grant read-only permissions to {% data variables.product.prodname_copilot_chat_short %}.
|
||||
* In the "{% data variables.product.prodname_copilot_short %}" settings, set your app type to "Agent," then fill out the remaining fields.
|
||||
|
||||
After you update your {% data variables.product.prodname_github_app %} settings, you can start chatting with your extension by typing `@YOUR-EXTENSION-NAME` in the {% data variables.product.prodname_copilot_chat_short %} window, then sending a prompt as normal.
|
||||
|
||||
For more detailed instructions, see "[AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent#configuring-your-github-app)."
|
||||
|
||||
{% endbash %}
|
||||
|
||||
## Next steps
|
||||
|
||||
Now that you have a working {% data variables.product.prodname_copilot_extension %}, you can try building on the Blackbeard agent to experiment with agent development.
|
||||
|
||||
To learn about more complex agent implementations, you can also review the following example agents and software development kit (SDK), all of which are available in the [`copilot-extensions`](https://github.com/copilot-extensions) organization:
|
||||
|
||||
* [{% data variables.product.prodname_github_models %}](https://github.com/copilot-extensions/github-models-extension): A more complex agent that lets you ask about and interact with various LLMs listed on the {% data variables.product.prodname_marketplace %} through {% data variables.product.prodname_copilot_chat_short %}. The {% data variables.product.prodname_github_models %} agent makes use of function calling.
|
||||
* [Function Calling](https://github.com/copilot-extensions/function-calling-extension): An example agent written in Go that demonstrates function calling and confirmation dialogs.
|
||||
* [RAG Extension](https://github.com/copilot-extensions/rag-extension): An example agent written in Go that demonstrates a simple implementation of retrieval augmented generation.
|
||||
* [Preview SDK](https://github.com/copilot-extensions/preview-sdk.js/tree/main): An SDK that streamlines the development of {% data variables.product.prodname_copilot_extensions_short %} by handling request verification, payload parsing, and response formatting automatically. This SDK allows extension builders to focus more on creating core functionality and less on boilerplate code.
|
||||
@@ -10,6 +10,8 @@ shortTitle: Set up Copilot Extensions
|
||||
|
||||
{% data reusables.copilot.copilot-extensions.beta-note %}
|
||||
|
||||
This article is designed to help you build an entirely new {% data variables.product.prodname_copilot_extension %}. To instead learn how to quickly build and test a demo {% data variables.product.prodname_copilot_extension_short %} created by {% data variables.product.github %}, see "[AUTOTITLE](/copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions)."
|
||||
|
||||
## 1. Learn about {% data variables.product.prodname_copilot_agents_short %}
|
||||
|
||||
{% data variables.product.prodname_copilot_agents_short %} contain the custom code for your {% data variables.product.prodname_copilot_extension_short %}, and integrate with a {% data variables.product.prodname_github_app %} to form the {% data variables.product.prodname_copilot_extension_short %} itself. For more information, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/about-copilot-agents)."
|
||||
|
||||
Reference in New Issue
Block a user