Skip to content

README.md

Latest commit

 

History

History
140 lines (98 loc) · 4.8 KB

README.md

File metadata and controls

140 lines (98 loc) · 4.8 KB
Raw

GitHub Copilot SDK — Tutorial Scripts

Self-contained Python CLI scripts that accompany the tutorial documentation at docs/copilot_sdk_tutorial/.

Each script runs standalone with uv run python <script>.py — no dependency on the template_github_copilot package.

Prerequisites

1. Python 3.13+ and uv

python --version   # 3.13 or later
uv --version       # https://docs.astral.sh/uv/

2. Install dependencies

All required packages (github-copilot-sdk, pydantic, azure-identity, …) are declared in pyproject.toml and are installed by uv sync:

cd src/python
uv sync --all-groups

3. Install and authenticate the Copilot CLI

The SDK launches the copilot CLI over stdio, so the binary must be installed.

# Option A: install via npm (provides the `copilot` command on PATH)
npm install -g @github/copilot

# Option B: let `gh copilot` download and manage the binary
gh copilot   # downloads on first run

# Authenticate with GitHub
gh auth login
# or: export COPILOT_GITHUB_TOKEN="<your-github-personal-access-token>"

If the copilot binary is not on your PATH, set COPILOT_CLI_PATH=/path/to/copilot.

The scripts do not require a separately running Copilot CLI server. Use --cli-url host:port only if you have one running in TCP mode.

Scripts

Script Tutorial What it demonstrates
01_chat_bot.py 01 — CLI Chatbot CopilotClient, session creation, single prompt, interactive loop
02_issue_triage.py 02 — Custom Tools @define_tool, Pydantic I/O, tool-calling agent
03_streaming_review.py 03 — Streaming ASSISTANT_MESSAGE_DELTA, real-time streaming output
04_skills_docgen.py 04 — Skills SKILL.md files, skills directory, doc generation
05_audit_hooks.py 05 — Hooks & Permissions session.on(), permission handler, audit log
06_byok_azure_openai.py 06 — BYOK ProviderConfig, Azure OpenAI API key & Entra ID

Quick Start

# 0. (once) Install and authenticate the Copilot CLI (see Prerequisites above)

# 1. Sync dependencies
cd src/python
uv sync --all-groups

# 2. Run a tutorial script
uv run python scripts/tutorials/01_chat_bot.py --help
uv run python scripts/tutorials/01_chat_bot.py --prompt "What is GitHub Copilot?"
uv run python scripts/tutorials/01_chat_bot.py --loop

uv run python scripts/tutorials/02_issue_triage.py

uv run python scripts/tutorials/03_streaming_review.py

uv run python scripts/tutorials/04_skills_docgen.py

# Default: the audit policy approves the delete_record tool call
uv run python scripts/tutorials/05_audit_hooks.py
# --deny-tools: the audit policy rejects the tool call (it is never executed)
uv run python scripts/tutorials/05_audit_hooks.py --deny-tools

# BYOK (requires Azure OpenAI setup)
export BYOK_BASE_URL="https://<resource>.openai.azure.com/openai/deployments/<deploy>"
export BYOK_API_KEY="<your-api-key>"
export BYOK_MODEL="gpt-4o"
uv run python scripts/tutorials/06_byok_azure_openai.py

Skills Directory

skills/ contains example SKILL.md files used by 04_skills_docgen.py.

skills/
├── docgen/
│   └── SKILL.md          # Google-style docstring generator
└── coding-standards/
    └── SKILL.md          # Coding standards checker

See 04 — Skills for details.

Observability (OpenTelemetry)

Every script can export OpenTelemetry traces. Telemetry is off by default; enable it with the shared --otel-* options or the equivalent environment variables wired through make_client() in _telemetry.py:

# Start the collector + Grafana LGTM stack (from the repository root)
docker compose -f docker/compose.yaml up -d

uv run python scripts/tutorials/01_chat_bot.py \
    --otel-endpoint http://localhost:4318 \
    --otel-bsp-schedule-delay 500 \
    --prompt "Hello!"

# View traces in Grafana → Explore → Tempo
open http://localhost:3000   # admin / admin

Equivalent environment variables: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, and OTEL_BSP_SCHEDULE_DELAY.

See Observability with OpenTelemetry and docker/README.md for details.