The Blackbeard extension is a GitHub Copilot Extension that comprises a GitHub App and a Copilot agent. The agent responds to chat requests in the style of a pirate, using Copilot's large language model (LLM) API and special system prompts. See About agents for Copilot Extensions.
This guide uses a simple agent implementation, but the process is similar for skillsets. For information about the difference between agents and skillsets, see About Copilot Extensions.
This quickstart is designed to help you build and chat with the Blackbeard extension as quickly as possible, so you can develop and test your extension without deploying infrastructure. For production, you'll need to host the application for your agent or skillset's endpoints on a publicly accessible server. To instead learn how to create a new GitHub Copilot Extension, see Setting up Copilot Extensions.
1. Create and install a GitHub App
In the developer settings for your GitHub account, create a GitHub App. Your 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 Creating a GitHub App for your Copilot Extension.
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.
- Using the Terminal built into VS Code, clone the
copilot-extensions/blackbeard-extensionrepository. - In the same Terminal, run
npm installto install the necessary dependencies, then runnpm startto start the Blackbeard agent on port 3000. - In the "Ports" tab of the VS Code panel, click Forward a port or Add port, then add port 3000.
- 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 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 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 Copilot Chat.
- In the "Copilot" settings, set your app type to "Agent," then fill out the remaining fields.
After you update your GitHub App settings, you can start chatting with your extension by typing @YOUR-EXTENSION-NAME in the Copilot Chat window, then sending a prompt as normal.
For more detailed instructions, see Configuring your GitHub App for your Copilot extension.
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.
- Navigate to the
copilot-extensions/blackbeard-extensionrepository. Select the Code dropdown menu, then click Create codespace on main. - To find your new codespace, select the Code dropdown menu. Next to your new codespace, select , then click Open in Browser.
- In the integrated Terminal, run
npm startto start the Blackbeard agent on port 3000. - In the "Ports" tab of the VS Code panel, click Forward a port, then add port 3000.
- 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 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 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 Copilot Chat.
- In the "Copilot" settings, set your app type to "Agent," then fill out the remaining fields.
After you update your GitHub App settings, you can start chatting with your extension by typing @YOUR-EXTENSION-NAME in the Copilot Chat window of a supported client or IDE, then sending a prompt as normal. For a list of supported clients and IDEs, see About Copilot Extensions.
Note
Chatting with GitHub Copilot Extensions in GitHub Codespaces is not supported.
For more detailed instructions, see Configuring your GitHub App for your Copilot extension.
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.
- Using your command line application, clone the
copilot-extensions/blackbeard-extensionrepository. - Run
npm installto install the necessary dependencies, then runnpm startto start the Blackbeard agent on port 3000.
3. Expose your local server
To make the Blackbeard agent accessible to the Copilot platform and 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.
-
Navigate to ngrok's download page, then install the appropriate version of ngrok for your operating system.
-
Navigate to the ngrok setup and installation page, then log in or sign up for an ngrok account.
-
To expose your local server, in a new window of your command line application, run the following command:
Shell ngrok http http://localhost:3000
ngrok http http://localhost:3000 -
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 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 Copilot Chat.
- In the "Copilot" settings, set your app type to "Agent," then fill out the remaining fields.
After you update your GitHub App settings, you can start chatting with your extension by typing @YOUR-EXTENSION-NAME in the Copilot Chat window, then sending a prompt as normal.
For more detailed instructions, see Configuring your GitHub App for your Copilot extension.
Next steps
Now that you have a working GitHub 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 organization:
- GitHub Models: A more complex agent that lets you ask about and interact with various LLMs listed on the GitHub Marketplace through Copilot Chat. The GitHub Models agent makes use of function calling.
- Function Calling: An example agent written in Go that demonstrates function calling and confirmation dialogs.
- RAG Extension: An example agent written in Go that demonstrates a simple implementation of retrieval augmented generation.
- Preview SDK: An SDK that streamlines the development of Copilot Extensions 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.