# 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
- **Node.js** 18+ ([Download](https://nodejs.org/))
- **npm** or **yarn**

#### Python
- **Python** 3.8+ ([Download](https://www.python.org/downloads/))
- **pip** or **uv** (recommended: [uv](https://github.com/astral-sh/uv))

#### Go
- **Go** 1.21+ ([Download](https://go.dev/doc/install))

#### .NET
- **.NET** 8.0+ ([Download](https://dotnet.microsoft.com/download))

## Quick Setup

### 1. Install GitHub CLI

If not already installed:

**macOS:**
```bash
brew install gh
```

**Linux:**
```bash
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:**
```powershell
winget install --id GitHub.cli
```

### 2. Install GitHub Copilot CLI

```bash
gh extension install github/gh-copilot
```

Verify installation:
```bash
copilot --version
```

### 3. Authenticate

```bash
gh auth login
```

Follow the prompts to authenticate with GitHub.

### 4. Install SDK for Your Language

#### Node.js / TypeScript

Create a new project:
```bash
mkdir my-agentic-app && cd my-agentic-app
npm init -y
npm install @github/copilot-sdk tsx
```

#### Python

Create a virtual environment (recommended):
```bash
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):
```bash
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install github-copilot-sdk
```

#### Go

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

#### .NET

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

## Development Environment Setup

### VS Code (Recommended)

1. Install [Visual Studio Code](https://code.visualstudio.com/)

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:
```bash
code .
```

### Environment Variables

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

```env
# 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

```bash
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`):**
```typescript
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:
```bash
npx tsx test.ts
```

**Python (`test.py`):**
```python
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:
```bash
python test.py
```

## Common Issues and Solutions

**Note:** For comprehensive troubleshooting, see the **[Troubleshooting Guide](./troubleshooting.md)**.

### Issue: `copilot: command not found`

**Solution:** Ensure GitHub CLI and Copilot extension are installed:
```bash
gh extension install github/gh-copilot
```

Add to your PATH if needed (Linux/macOS):
```bash
export PATH="$PATH:$HOME/.local/bin"
```

### Issue: Authentication Errors

**Solution:** Re-authenticate:
```bash
gh auth login
gh auth refresh -s copilot
```

### Issue: SDK Import Errors

**Node.js:** Ensure dependencies are installed:
```bash
npm install
```

**Python:** Activate virtual environment:
```bash
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:
```bash
pkill -f copilot
```

### Issue: Module Not Found in Python

**Solution:** Install in development mode:
```bash
pip install -e .
```

**For more issues and solutions, see the [Troubleshooting Guide](./troubleshooting.md).**

## Advanced Configuration

### Using a Specific Copilot CLI Version

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

### Configuring Tool Access

Control which tools are available to agents:

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

### Connecting to External CLI Server

```typescript
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](./getting-started.md)
2. **Explore Cookbook Examples**: [cookbook/](../cookbook/)
3. **Build Your First Agent**: Start with a simple custom tool
4. **Join the Community**: Check [GitHub Discussions](https://github.com/github/copilot-sdk/discussions)

## Additional Resources

- [GitHub Copilot CLI Documentation](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line)
- [SDK API Reference](../README.md#available-sdks)
- [MCP Servers](https://github.com/modelcontextprotocol/servers) - Pre-built tool servers
- [Contributing Guide](../CONTRIBUTING.md)

## Need Help?

- **Issues**: [GitHub Issues](https://github.com/github/copilot-sdk/issues)
- **Discussions**: [GitHub Discussions](https://github.com/github/copilot-sdk/discussions)
- **Documentation**: [Main README](../README.md)