From 0314778319be13292bc1b092a258ae4b7d080df7 Mon Sep 17 00:00:00 2001 From: sahiixx Date: Mon, 10 Aug 2026 09:11:51 +0000 Subject: [PATCH 1/2] chore(fork): add AGENTS.md with Azure Foundry model routing --- AGENTS.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..7392c86bf1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# Agent Instructions — copilot-sdk (fork) + +> **This is a fork.** These instructions are local to this fork and are not +> intended for upstream. Exclude this file from any upstream pull request. + +## Models (Azure Foundry — resource `admin-3443-resourche`) + +| Purpose | Deployment | Endpoint | +|---|---|---| +| Default / general | `gpt-5.6-sol` | `/openai/v1/chat/completions` | +| Deep reasoning | `claude-opus-5` | `/openai/v1/responses` **only** | +| Legacy / stable | `gpt-5` | `/openai/v1/chat/completions` | +| Embeddings | `text-embedding-3-small` | `/openai/v1/embeddings` | + +Base URL: `https://admin-3443-resourche.openai.azure.com/openai/v1` +Auth: `api-key` header from `$AZURE_FOUNDRY_API_KEY`. **Never hardcode the key.** + +### Known constraint +`claude-opus-5` returns HTTP 404 `api_not_supported` on `/chat/completions`. +It answers **only** via the Responses API. + +## Hermes usage + +``` +/model azure # gpt-5.6-sol (default) +/model azure-opus # claude-opus-5 +/model azure-gpt5 # gpt-5 +``` + +## Fork conventions + +- Keep fork-local changes in separate commits from upstream-bound work. +- Rebase on upstream before opening a PR; drop this file from the PR branch. +- Secrets live in environment variables, never in tracked files. From c2184d960fa430c01bd46e0cc049b303776ea59d Mon Sep 17 00:00:00 2001 From: sahiixx Date: Mon, 10 Aug 2026 09:43:32 +0000 Subject: [PATCH 2/2] docs: regenerate fork-local README via agentic harness --- README.md | 194 ++++++++++++++++++++++----------------------- README.original.md | 137 ++++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+), 99 deletions(-) create mode 100644 README.original.md diff --git a/README.md b/README.md index bf74289bc0..83abbb0a9d 100644 --- a/README.md +++ b/README.md @@ -1,137 +1,133 @@ -# GitHub Copilot CLI SDKs +# copilot-sdk -![GitHub Copilot SDK](./assets/RepoHeader_01.png) - -[![NPM Downloads](https://img.shields.io/npm/dm/%40github%2Fcopilot-sdk?label=npm)](https://www.npmjs.com/package/@github/copilot-sdk) -[![PyPI - Downloads](https://img.shields.io/pypi/dm/github-copilot-sdk?label=PyPI)](https://pypi.org/project/github-copilot-sdk/) -[![NuGet Downloads](https://img.shields.io/nuget/dt/GitHub.Copilot.SDK?label=NuGet)](https://www.nuget.org/packages/GitHub.Copilot.SDK) +![Agentic](https://img.shields.io/badge/agentic-harness-purple) ![Fork](https://img.shields.io/badge/repo-fork-orange) Agents for every app. -Embed Copilot's agentic workflows in your application—now available in Technical preview as a programmable SDK for Python, TypeScript, Go, and .NET. - -The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production-tested agent runtime you can invoke programmatically. No need to build your own orchestration—you define agent behavior, Copilot handles planning, tool invocation, file edits, and more. - -## Available SDKs - -| SDK | Location | Installation | -| ------------------------ | ------------------------------------------------- | ----------------------------------------- | -| **Node.js / TypeScript** | [`cookbook/nodejs/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/nodejs/README.md) | `npm install @github/copilot-sdk` | -| **Python** | [`cookbook/python/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/python/README.md) | `pip install github-copilot-sdk` | -| **Go** | [`cookbook/go/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/go/README.md) | `go get github.com/github/copilot-sdk/go` | -| **.NET** | [`cookbook/dotnet/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/dotnet/README.md) | `dotnet add package GitHub.Copilot.SDK` | - -See the individual SDK READMEs for installation, usage examples, and API reference. - -## Getting Started - -For a complete walkthrough, see the **[Getting Started Guide](./docs/getting-started.md)**. +> **Fork.** This README is generated by the [agentic harness](https://github.com/sahiixx/agentic-harness) and is +> **fork-local** — exclude it from any upstream pull request. Upstream docs are +> preserved in `README.original.md`. -Quick steps: +## Table of Contents -1. **Install the Copilot CLI:** +- [Overview](#overview) +- [Quick Start](#quick-start) +- [Agentic Architecture](#agentic-architecture) +- [Model Routing](#model-routing) +- [Project Layout](#project-layout) +- [Development](#development) +- [Related Repositories](#related-repositories) - Follow the [Copilot CLI installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) to install the CLI, or ensure `copilot` is available in your PATH. +## Overview -2. **Install your preferred SDK** using the commands above. +Agents for every app. -3. **See the SDK README** for usage examples and API documentation. +| | | +|---|---| +| **Stack** | — | +| **Frameworks** | — | +| **Tests** | yes | +| **Commits** | 2 | +| **Last activity** | 2026-08-10 | +| **Origin** | fork of upstream | -## Architecture +## Quick Start -All SDKs communicate with the Copilot CLI server via JSON-RPC: +### Install +```bash +# No dependency manifest detected — see source layout below. ``` -Your Application - ↓ - SDK Client - ↓ JSON-RPC - Copilot CLI (server mode) -``` - -The SDK manages the CLI process lifecycle automatically. You can also connect to an external CLI server—see the [Getting Started Guide](./docs/getting-started.md#connecting-to-an-external-cli-server) for details on running the CLI in server mode. - -## FAQ - -### Do I need a GitHub Copilot subscription to use the SDK? - -Yes, a GitHub Copilot subscription is required to use the GitHub Copilot SDK, **unless you are using BYOK (Bring Your Own Key)**. With BYOK, you can use the SDK without GitHub authentication by configuring your own API keys from supported LLM providers. For standard usage (non-BYOK), refer to the [GitHub Copilot pricing page](https://github.com/features/copilot#pricing), which includes a free tier with limited usage. -### How does billing work for SDK usage? +### Run -Billing for the GitHub Copilot SDK is based on the same model as the Copilot CLI, with each prompt being counted towards your premium request quota. For more information on premium requests, see [Requests in GitHub Copilot](https://docs.github.com/en/copilot/concepts/billing/copilot-requests). - -### Does it support BYOK (Bring Your Own Key)? - -Yes, the GitHub Copilot SDK supports BYOK (Bring Your Own Key). You can configure the SDK to use your own API keys from supported LLM providers (e.g. OpenAI, Azure AI Foundry, Anthropic) to access models through those providers. See the **[BYOK documentation](./docs/auth/byok.md)** for setup instructions and examples. - -**Note:** BYOK uses key-based authentication only. Microsoft Entra ID (Azure AD), managed identities, and third-party identity providers are not supported. - -### What authentication methods are supported? - -The SDK supports multiple authentication methods: -- **GitHub signed-in user** - Uses stored OAuth credentials from `copilot` CLI login -- **OAuth GitHub App** - Pass user tokens from your GitHub OAuth app -- **Environment variables** - `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` -- **BYOK** - Use your own API keys (no GitHub auth required) - -See the **[Authentication documentation](./docs/auth/index.md)** for details on each method. - -### Do I need to install the Copilot CLI separately? +```bash +# Entry point not auto-detected; inspect the layout below. +``` -Yes, the Copilot CLI must be installed separately. The SDKs communicate with the Copilot CLI in server mode to provide agent capabilities. +## Agentic Architecture -### What tools are enabled by default? +This fork participates in the [sahiixx agentic harness](https://github.com/sahiixx/agentic-harness) — a shared +contract for how agents plan, act, verify, and recover across the account. -By default, the SDK will operate the Copilot CLI in the equivalent of `--allow-all` being passed to the CLI, enabling all first-party tools, which means that the agents can perform a wide range of actions, including file system operations, Git operations, and web requests. You can customize tool availability by configuring the SDK client options to enable and disable specific tools. Refer to the individual SDK documentation for details on tool configuration and Copilot CLI for the list of tools available. +> **Fork note:** this file is fork-local. Drop it from any branch you open as a +> pull request upstream. The harness contract also lives in `AGENTS.md`. -### Can I use custom agents, skills or tools? +**Signal strength:** agentic density score `958`. -Yes, the GitHub Copilot SDK allows you to define custom agents, skills, and tools. You can extend the functionality of the agents by implementing your own logic and integrating additional tools as needed. Refer to the SDK documentation of your preferred language for more details. +### Patterns in play -### Are there instructions for Copilot to speed up development with the SDK? +| Pattern | Role here | +|---|---| +| **Prompt Chaining** | Deterministic multi-step pipelines with known subtasks | +| **Routing** | Classify input, dispatch to the specialist path | +| **Parallelization** | Independent subtasks fan out; results aggregated | +| **Orchestrator–Workers** | Central planner decomposes dynamically | +| **Evaluator–Optimizer** | Generator/judge split with explicit rubric; bounded retry | +| **ReAct** | Interleaved reason → act → observe for adaptive tool use | +| **Reflection** | Self-critique before emitting a final answer | -Yes, check out the custom instructions at [`github/awesome-copilot`](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md). +### Reliability envelope -### What models are supported? +- **Bounded execution** — every loop has a max-iteration and wall-clock ceiling. +- **Tool sandboxing** — filesystem/network side effects isolated and reversible. +- **Guardrail layering** — validate at input, mid-loop, and output. +- **Context engineering** — select, compress, isolate; never grow unbounded. +- **Self-verification** — check intermediate output against constraints. -All models available via Copilot CLI are supported in the SDK. The SDK also exposes a method which will return the models available so they can be accessed at runtime. +## Model Routing -### Is the SDK production-ready? +Agent work in this fork routes through Azure AI Foundry. See [`AGENTS.md`](./AGENTS.md). -The GitHub Copilot SDK is currently in Technical Preview. While it is functional and can be used for development and testing, it may not yet be suitable for production use. +| Purpose | Deployment | Endpoint | +|---|---|---| +| Default / general | `gpt-5.6-sol` | `/openai/v1/chat/completions` | +| Deep reasoning | `claude-opus-5` | `/openai/v1/responses` **only** | +| Embeddings | `text-embedding-3-small` | `/openai/v1/embeddings` | -### How do I report issues or request features? +```bash +export AZURE_FOUNDRY_API_KEY=... # never commit this +export AZURE_FOUNDRY_BASE_URL=https://.openai.azure.com/openai/v1 +``` -Please use the [GitHub Issues](https://github.com/github/copilot-sdk/issues) page to report bugs or request new features. We welcome your feedback to help improve the SDK. +> **Gotcha:** Claude deployments on Azure return `404 api_not_supported` on +> `/chat/completions`. They answer **only** via the Responses API. -## Quick Links +## Project Layout -- **[Getting Started](./docs/getting-started.md)** – Tutorial to get up and running -- **[Authentication](./docs/auth/index.md)** – GitHub OAuth, BYOK, and more -- **[Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk)** – Practical recipes for common tasks across all languages -- **[More Resources](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md)** – Additional examples, tutorials, and community resources +``` +AGENTS.md +CODE_OF_CONDUCT.md +CONTRIBUTING.md +LICENSE +README.md +SECURITY.md +SUPPORT.md +assets/ +docs/ +dotnet/ +go/ +justfile +nodejs/ +python/ +``` -## Unofficial, Community-maintained SDKs +## Development -⚠️ Disclaimer: These are unofficial, community-driven SDKs and they are not supported by GitHub. Use at your own risk. +```bash +# no linter configured +gh workflow run hermes-azure-check.yml +``` -| SDK | Location | -| --------------| -------------------------------------------------- | -| **Java** | [copilot-community-sdk/copilot-sdk-java][sdk-java] | -| **Rust** | [copilot-community-sdk/copilot-sdk-rust][sdk-rust] | -| **C++** | [0xeb/copilot-sdk-cpp][sdk-cpp] | -| **Clojure** | [krukow/copilot-sdk-clojure][sdk-clojure] | +Secrets live in environment variables and CI secrets — never in tracked files. -[sdk-java]: https://github.com/copilot-community-sdk/copilot-sdk-java -[sdk-rust]: https://github.com/copilot-community-sdk/copilot-sdk-rust -[sdk-cpp]: https://github.com/0xeb/copilot-sdk-cpp -[sdk-clojure]: https://github.com/krukow/copilot-sdk-clojure +## Related Repositories -## Contributing +Part of a 226-repository workspace sharing one agentic contract: -See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines. +- **[agentic-harness](https://github.com/sahiixx/agentic-harness)** — patterns, contracts, reference implementations +- `AGENTS.md` in every repo pins identical model routing -## License +--- -MIT +README maintained by the agentic harness · fork-local · regenerated 2026-08-10 diff --git a/README.original.md b/README.original.md new file mode 100644 index 0000000000..bf74289bc0 --- /dev/null +++ b/README.original.md @@ -0,0 +1,137 @@ +# GitHub Copilot CLI SDKs + +![GitHub Copilot SDK](./assets/RepoHeader_01.png) + +[![NPM Downloads](https://img.shields.io/npm/dm/%40github%2Fcopilot-sdk?label=npm)](https://www.npmjs.com/package/@github/copilot-sdk) +[![PyPI - Downloads](https://img.shields.io/pypi/dm/github-copilot-sdk?label=PyPI)](https://pypi.org/project/github-copilot-sdk/) +[![NuGet Downloads](https://img.shields.io/nuget/dt/GitHub.Copilot.SDK?label=NuGet)](https://www.nuget.org/packages/GitHub.Copilot.SDK) + +Agents for every app. + +Embed Copilot's agentic workflows in your application—now available in Technical preview as a programmable SDK for Python, TypeScript, Go, and .NET. + +The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production-tested agent runtime you can invoke programmatically. No need to build your own orchestration—you define agent behavior, Copilot handles planning, tool invocation, file edits, and more. + +## Available SDKs + +| SDK | Location | Installation | +| ------------------------ | ------------------------------------------------- | ----------------------------------------- | +| **Node.js / TypeScript** | [`cookbook/nodejs/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/nodejs/README.md) | `npm install @github/copilot-sdk` | +| **Python** | [`cookbook/python/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/python/README.md) | `pip install github-copilot-sdk` | +| **Go** | [`cookbook/go/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/go/README.md) | `go get github.com/github/copilot-sdk/go` | +| **.NET** | [`cookbook/dotnet/`](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/dotnet/README.md) | `dotnet add package GitHub.Copilot.SDK` | + +See the individual SDK READMEs for installation, usage examples, and API reference. + +## Getting Started + +For a complete walkthrough, see the **[Getting Started Guide](./docs/getting-started.md)**. + +Quick steps: + +1. **Install the Copilot CLI:** + + Follow the [Copilot CLI installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) to install the CLI, or ensure `copilot` is available in your PATH. + +2. **Install your preferred SDK** using the commands above. + +3. **See the SDK README** for usage examples and API documentation. + +## Architecture + +All SDKs communicate with the Copilot CLI server via JSON-RPC: + +``` +Your Application + ↓ + SDK Client + ↓ JSON-RPC + Copilot CLI (server mode) +``` + +The SDK manages the CLI process lifecycle automatically. You can also connect to an external CLI server—see the [Getting Started Guide](./docs/getting-started.md#connecting-to-an-external-cli-server) for details on running the CLI in server mode. + +## FAQ + +### Do I need a GitHub Copilot subscription to use the SDK? + +Yes, a GitHub Copilot subscription is required to use the GitHub Copilot SDK, **unless you are using BYOK (Bring Your Own Key)**. With BYOK, you can use the SDK without GitHub authentication by configuring your own API keys from supported LLM providers. For standard usage (non-BYOK), refer to the [GitHub Copilot pricing page](https://github.com/features/copilot#pricing), which includes a free tier with limited usage. + +### How does billing work for SDK usage? + +Billing for the GitHub Copilot SDK is based on the same model as the Copilot CLI, with each prompt being counted towards your premium request quota. For more information on premium requests, see [Requests in GitHub Copilot](https://docs.github.com/en/copilot/concepts/billing/copilot-requests). + +### Does it support BYOK (Bring Your Own Key)? + +Yes, the GitHub Copilot SDK supports BYOK (Bring Your Own Key). You can configure the SDK to use your own API keys from supported LLM providers (e.g. OpenAI, Azure AI Foundry, Anthropic) to access models through those providers. See the **[BYOK documentation](./docs/auth/byok.md)** for setup instructions and examples. + +**Note:** BYOK uses key-based authentication only. Microsoft Entra ID (Azure AD), managed identities, and third-party identity providers are not supported. + +### What authentication methods are supported? + +The SDK supports multiple authentication methods: +- **GitHub signed-in user** - Uses stored OAuth credentials from `copilot` CLI login +- **OAuth GitHub App** - Pass user tokens from your GitHub OAuth app +- **Environment variables** - `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` +- **BYOK** - Use your own API keys (no GitHub auth required) + +See the **[Authentication documentation](./docs/auth/index.md)** for details on each method. + +### Do I need to install the Copilot CLI separately? + +Yes, the Copilot CLI must be installed separately. The SDKs communicate with the Copilot CLI in server mode to provide agent capabilities. + +### What tools are enabled by default? + +By default, the SDK will operate the Copilot CLI in the equivalent of `--allow-all` being passed to the CLI, enabling all first-party tools, which means that the agents can perform a wide range of actions, including file system operations, Git operations, and web requests. You can customize tool availability by configuring the SDK client options to enable and disable specific tools. Refer to the individual SDK documentation for details on tool configuration and Copilot CLI for the list of tools available. + +### Can I use custom agents, skills or tools? + +Yes, the GitHub Copilot SDK allows you to define custom agents, skills, and tools. You can extend the functionality of the agents by implementing your own logic and integrating additional tools as needed. Refer to the SDK documentation of your preferred language for more details. + +### Are there instructions for Copilot to speed up development with the SDK? + +Yes, check out the custom instructions at [`github/awesome-copilot`](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md). + +### What models are supported? + +All models available via Copilot CLI are supported in the SDK. The SDK also exposes a method which will return the models available so they can be accessed at runtime. + +### Is the SDK production-ready? + +The GitHub Copilot SDK is currently in Technical Preview. While it is functional and can be used for development and testing, it may not yet be suitable for production use. + +### How do I report issues or request features? + +Please use the [GitHub Issues](https://github.com/github/copilot-sdk/issues) page to report bugs or request new features. We welcome your feedback to help improve the SDK. + +## Quick Links + +- **[Getting Started](./docs/getting-started.md)** – Tutorial to get up and running +- **[Authentication](./docs/auth/index.md)** – GitHub OAuth, BYOK, and more +- **[Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk)** – Practical recipes for common tasks across all languages +- **[More Resources](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md)** – Additional examples, tutorials, and community resources + +## Unofficial, Community-maintained SDKs + +⚠️ Disclaimer: These are unofficial, community-driven SDKs and they are not supported by GitHub. Use at your own risk. + +| SDK | Location | +| --------------| -------------------------------------------------- | +| **Java** | [copilot-community-sdk/copilot-sdk-java][sdk-java] | +| **Rust** | [copilot-community-sdk/copilot-sdk-rust][sdk-rust] | +| **C++** | [0xeb/copilot-sdk-cpp][sdk-cpp] | +| **Clojure** | [krukow/copilot-sdk-clojure][sdk-clojure] | + +[sdk-java]: https://github.com/copilot-community-sdk/copilot-sdk-java +[sdk-rust]: https://github.com/copilot-community-sdk/copilot-sdk-rust +[sdk-cpp]: https://github.com/0xeb/copilot-sdk-cpp +[sdk-clojure]: https://github.com/krukow/copilot-sdk-clojure + +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines. + +## License + +MIT