Skip to content

environment-setup.md

Latest commit

 

History

History
339 lines (247 loc) · 7.59 KB

environment-setup.md

File metadata and controls

339 lines (247 loc) · 7.59 KB

Environment Setup for Agentic App Development

This guide walks you through setting up your development environment to build agentic applications using the GitHub Copilot SDK.

Overview

To develop agentic apps with the Copilot SDK, you'll need:

  1. GitHub Copilot CLI - The core agent runtime
  2. SDK for your preferred language - Python, TypeScript, Go, or .NET
  3. Development tools - IDE, package managers, and runtime environments

Prerequisites

Required

  • GitHub Account with Copilot access
  • GitHub CLI (gh) installed and authenticated
  • Git installed

Choose Your Language Stack

Pick one or more SDKs to work with:

Node.js / TypeScript

Python

  • Python 3.8+ (Download)
  • pip or uv (recommended: uv)

Go

.NET

Quick Setup

1. Install GitHub CLI

If not already installed:

macOS:

brew install gh

Linux:

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Windows:

winget install --id GitHub.cli

2. Install GitHub Copilot CLI

gh extension install github/gh-copilot

Verify installation:

copilot --version

3. Authenticate

gh auth login

Follow the prompts to authenticate with GitHub.

4. Install SDK for Your Language

Node.js / TypeScript

Create a new project:

mkdir my-agentic-app && cd my-agentic-app
npm init -y
npm install @github/copilot-sdk tsx

Python

Create a virtual environment (recommended):

mkdir my-agentic-app && cd my-agentic-app
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install github-copilot-sdk

Or with uv (faster):

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install github-copilot-sdk

Go

mkdir my-agentic-app && cd my-agentic-app
go mod init my-agentic-app
go get github.com/github/copilot-sdk/go

.NET

dotnet new console -n MyAgenticApp
cd MyAgenticApp
dotnet add package GitHub.Copilot.SDK

Development Environment Setup

VS Code (Recommended)

  1. Install Visual Studio Code

  2. Install recommended extensions:

    • GitHub Copilot
    • GitHub Copilot Chat
    • Language-specific extensions:
      • TypeScript: ESLint, Prettier
      • Python: Python, Pylance
      • Go: Go
      • .NET: C# Dev Kit

  3. Open your project:

code .

Environment Variables

Create a .env file in your project root for configuration:

# GitHub Copilot Configuration
COPILOT_MODEL=gpt-4.1
COPILOT_STREAMING=true

# Optional: Custom CLI path
COPILOT_CLI_PATH=/path/to/copilot

# Optional: Logging
LOG_LEVEL=info

Note: Never commit .env files with sensitive data. Add .env to your .gitignore.

Project Structure

Recommended structure for agentic apps:

my-agentic-app/
├── .env.example          # Template for environment variables
├── .gitignore            # Ignore node_modules, venv, etc.
├── README.md             # Project documentation
├── src/                  # Source code
│   ├── agents/           # Custom agent definitions
│   ├── tools/            # Custom tool implementations
│   └── main.[ts|py|go|cs]  # Entry point
└── tests/                # Test files

Validating Your Setup

Test the Copilot CLI

copilot "what is 2+2?"

You should see a response from Copilot.

Test the SDK

Create a simple test file to verify the SDK works:

TypeScript (test.ts):

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({ model: "gpt-4.1" });
const response = await session.sendAndWait({ prompt: "Say hello!" });
if (response?.data.content) {
    console.log(response.data.content);
} else {
    console.log("No response received");
}
await client.stop();

Run:

npx tsx test.ts

Python (test.py):

import asyncio
from copilot import CopilotClient

async def main():
    client = CopilotClient()
    await client.start()
    session = await client.create_session({"model": "gpt-4.1"})
    response = await session.send_and_wait({"prompt": "Say hello!"})
    print(response.data.content)
    await client.stop()

asyncio.run(main())

Run:

python test.py

Common Issues and Solutions

Note: For comprehensive troubleshooting, see the Troubleshooting Guide.

Issue: copilot: command not found

Solution: Ensure GitHub CLI and Copilot extension are installed:

gh extension install github/gh-copilot

Add to your PATH if needed (Linux/macOS):

export PATH="$PATH:$HOME/.local/bin"

Issue: Authentication Errors

Solution: Re-authenticate:

gh auth login
gh auth refresh -s copilot

Issue: SDK Import Errors

Node.js: Ensure dependencies are installed:

npm install

Python: Activate virtual environment:

source venv/bin/activate  # or .venv/bin/activate
pip install github-copilot-sdk

Issue: Port Already in Use

The SDK starts the Copilot CLI in server mode. If you see port conflicts:

Solution: The SDK handles this automatically, but if issues persist, kill existing processes:

pkill -f copilot

Issue: Module Not Found in Python

Solution: Install in development mode:

pip install -e .

For more issues and solutions, see the Troubleshooting Guide.

Advanced Configuration

Using a Specific Copilot CLI Version

const client = new CopilotClient({
    cliPath: "/path/to/specific/copilot",
});

Configuring Tool Access

Control which tools are available to agents:

const session = await client.createSession({
    tools: [myCustomTool],
    allowAll: false,  // Disable default tools
});

Connecting to External CLI Server

const client = new CopilotClient({
    serverUrl: "http://localhost:8080",
});

Next Steps

Now that your environment is set up:

  1. Read the Getting Started Guide: docs/getting-started.md
  2. Explore Cookbook Examples: cookbook/
  3. Build Your First Agent: Start with a simple custom tool
  4. Join the Community: Check GitHub Discussions

Additional Resources

Need Help?