diff --git a/README.md b/README.md index 65a2339c8..d302797f4 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,19 @@ 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, .NET, and Java. +Embed Copilot's agentic workflows in your application—now available in public preview as a programmable SDK for Python, TypeScript, Go, .NET, and Java. 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 | Cookbook | Installation | -| ------------------------ | -------------- | ------------------------------------------------- | ----------------------------------------- | -| **Node.js / TypeScript** | [`nodejs/`](./nodejs/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/nodejs/README.md) | `npm install @github/copilot-sdk` | -| **Python** | [`python/`](./python/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/python/README.md) | `pip install github-copilot-sdk` | -| **Go** | [`go/`](./go/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/go/README.md) | `go get github.com/github/copilot-sdk/go` | -| **.NET** | [`dotnet/`](./dotnet/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/dotnet/README.md) | `dotnet add package GitHub.Copilot.SDK` | -| **Java** | [`github/copilot-sdk-java`](https://github.com/github/copilot-sdk-java) | WIP | Maven coordinates
`com.github:copilot-sdk-java`
See instructions for [Maven](https://github.com/github/copilot-sdk-java?tab=readme-ov-file#maven) and [Gradle](https://github.com/github/copilot-sdk-java?tab=readme-ov-file#gradle) | +| SDK | Location | Cookbook | Installation | +| ------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Node.js / TypeScript** | [`nodejs/`](./nodejs/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/nodejs/README.md) | `npm install @github/copilot-sdk` | +| **Python** | [`python/`](./python/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/python/README.md) | `pip install github-copilot-sdk` | +| **Go** | [`go/`](./go/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/go/README.md) | `go get github.com/github/copilot-sdk/go` | +| **.NET** | [`dotnet/`](./dotnet/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/dotnet/README.md) | `dotnet add package GitHub.Copilot.SDK` | +| **Java** | [`github/copilot-sdk-java`](https://github.com/github/copilot-sdk-java) | WIP | Maven coordinates
`com.github:copilot-sdk-java`
See instructions for [Maven](https://github.com/github/copilot-sdk-java?tab=readme-ov-file#maven) and [Gradle](https://github.com/github/copilot-sdk-java?tab=readme-ov-file#gradle) | See the individual SDK READMEs for installation, usage examples, and API reference. @@ -71,6 +71,7 @@ Yes, the GitHub Copilot SDK supports BYOK (Bring Your Own Key). You can configur ### 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` @@ -100,14 +101,13 @@ Yes, check out the custom instructions for each SDK: - **[Go](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-go.instructions.md)** - **[Java](https://github.com/github/copilot-sdk-java/blob/main/instructions/copilot-sdk-java.instructions.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. +The GitHub Copilot SDK is currently in Public 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? @@ -128,11 +128,11 @@ Please use the [GitHub Issues](https://github.com/github/copilot-sdk/issues) pag ⚠️ Disclaimer: These are unofficial, community-driven SDKs and they are not supported by GitHub. Use at your own risk. -| SDK | Location | -| --------------| ----------------------------------------------------------------- | -| **Rust** | [copilot-community-sdk/copilot-sdk-rust][sdk-rust] | -| **Clojure** | [copilot-community-sdk/copilot-sdk-clojure][sdk-clojure] | -| **C++** | [0xeb/copilot-sdk-cpp][sdk-cpp] | +| SDK | Location | +| ----------- | -------------------------------------------------------- | +| **Rust** | [copilot-community-sdk/copilot-sdk-rust][sdk-rust] | +| **Clojure** | [copilot-community-sdk/copilot-sdk-clojure][sdk-clojure] | +| **C++** | [0xeb/copilot-sdk-cpp][sdk-cpp] | [sdk-rust]: https://github.com/copilot-community-sdk/copilot-sdk-rust [sdk-cpp]: https://github.com/0xeb/copilot-sdk-cpp diff --git a/dotnet/README.md b/dotnet/README.md index 151255e5f..4e6cd7c4e 100644 --- a/dotnet/README.md +++ b/dotnet/README.md @@ -2,7 +2,7 @@ SDK for programmatic control of GitHub Copilot CLI. -> **Note:** This SDK is in technical preview and may change in breaking ways. +> **Note:** This SDK is in public preview and may change in breaking ways. ## Installation @@ -170,6 +170,7 @@ using var subscription = client.On(SessionLifecycleEventTypes.Foreground, evt => ``` **Lifecycle Event Types:** + - `SessionLifecycleEventTypes.Created` - A new session was created - `SessionLifecycleEventTypes.Deleted` - A session was deleted - `SessionLifecycleEventTypes.Updated` - A session was updated @@ -766,13 +767,13 @@ var session = await client.CreateSessionAsync(new SessionConfig ### Permission Result Kinds -| Value | Meaning | -|-------|---------| -| `PermissionRequestResultKind.Approved` | Allow the tool to run | -| `PermissionRequestResultKind.DeniedInteractivelyByUser` | User explicitly denied the request | -| `PermissionRequestResultKind.DeniedCouldNotRequestFromUser` | No approval rule matched and user could not be asked | -| `PermissionRequestResultKind.DeniedByRules` | Denied by a policy rule | -| `PermissionRequestResultKind.NoResult` | Leave the permission request unanswered (the SDK returns without calling the RPC). Not allowed for protocol v2 permission requests (will be rejected). | +| Value | Meaning | +| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `PermissionRequestResultKind.Approved` | Allow the tool to run | +| `PermissionRequestResultKind.DeniedInteractivelyByUser` | User explicitly denied the request | +| `PermissionRequestResultKind.DeniedCouldNotRequestFromUser` | No approval rule matched and user could not be asked | +| `PermissionRequestResultKind.DeniedByRules` | Denied by a policy rule | +| `PermissionRequestResultKind.NoResult` | Leave the permission request unanswered (the SDK returns without calling the RPC). Not allowed for protocol v2 permission requests (will be rejected). | ### Resuming Sessions diff --git a/go/README.md b/go/README.md index 46356eabf..654f3d369 100644 --- a/go/README.md +++ b/go/README.md @@ -2,7 +2,7 @@ A Go SDK for programmatic access to the GitHub Copilot CLI. -> **Note:** This SDK is in technical preview and may change in breaking ways. +> **Note:** This SDK is in public preview and may change in breaking ways. ## Installation @@ -180,7 +180,7 @@ Event types: `SessionLifecycleCreated`, `SessionLifecycleDeleted`, `SessionLifec - `Abort(ctx context.Context) error` - Abort the currently processing message - `GetMessages(ctx context.Context) ([]SessionEvent, error)` - Get message history - `Disconnect() error` - Disconnect the session (releases in-memory resources, preserves disk state) -- `Destroy() error` - *(Deprecated)* Use `Disconnect()` instead +- `Destroy() error` - _(Deprecated)_ Use `Disconnect()` instead - `UI() *SessionUI` - Interactive UI API for elicitation dialogs - `Capabilities() SessionCapabilities` - Host capabilities (e.g. elicitation support) @@ -230,6 +230,7 @@ session, err := client.CreateSession(ctx, &copilot.SessionConfig{ Available section constants: `SectionIdentity`, `SectionTone`, `SectionToolEfficiency`, `SectionEnvironmentContext`, `SectionCodeChangeRules`, `SectionGuidelines`, `SectionSafety`, `SectionToolInstructions`, `SectionCustomInstructions`, `SectionLastInstructions`. Each section override supports four actions: + - **`replace`** — Replace the section content entirely - **`remove`** — Remove the section from the prompt - **`append`** — Add content after the existing section @@ -543,7 +544,9 @@ session, err := client.CreateSession(context.Background(), &copilot.SessionConfi }, }) ``` + > **Important notes:** +> > - When using a custom provider, the `Model` parameter is **required**. The SDK will return an error if no model is specified. > - For Azure OpenAI endpoints (`*.openai.azure.com`), you **must** use `Type: "azure"`, not `Type: "openai"`. > - The `BaseURL` should be just the host (e.g., `https://my-resource.openai.azure.com`). Do **not** include `/openai/v1` in the URL - the SDK handles path construction automatically. @@ -623,13 +626,13 @@ session, err := client.CreateSession(context.Background(), &copilot.SessionConfi ### Permission Result Kinds -| Constant | Meaning | -|----------|---------| -| `PermissionRequestResultKindApproved` | Allow the tool to run | -| `PermissionRequestResultKindDeniedInteractivelyByUser` | User explicitly denied the request | -| `PermissionRequestResultKindDeniedCouldNotRequestFromUser` | No approval rule matched and user could not be asked | -| `PermissionRequestResultKindDeniedByRules` | Denied by a policy rule | -| `PermissionRequestResultKindNoResult` | Leave the permission request unanswered (protocol v1 only; not allowed for protocol v2) | +| Constant | Meaning | +| ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| `PermissionRequestResultKindApproved` | Allow the tool to run | +| `PermissionRequestResultKindDeniedInteractivelyByUser` | User explicitly denied the request | +| `PermissionRequestResultKindDeniedCouldNotRequestFromUser` | No approval rule matched and user could not be asked | +| `PermissionRequestResultKindDeniedByRules` | Denied by a policy rule | +| `PermissionRequestResultKindNoResult` | Leave the permission request unanswered (protocol v1 only; not allowed for protocol v2) | ### Resuming Sessions @@ -840,6 +843,7 @@ session, err := client.CreateSession(ctx, &copilot.SessionConfig{ ``` When `OnElicitationRequest` is provided, the SDK automatically: + - Sends `requestElicitation: true` in the create/resume payload - Routes `elicitation.requested` events to your handler - Auto-cancels the request if your handler returns an error (so the server doesn't hang) diff --git a/java/README.md b/java/README.md index 609c7365b..ca1ee099d 100644 --- a/java/README.md +++ b/java/README.md @@ -4,7 +4,7 @@ Java SDK for programmatic control of GitHub Copilot CLI via JSON-RPC. > **📦 The Java SDK is maintained in a separate repository: [`github/copilot-sdk-java`](https://github.com/github/copilot-sdk-java)** > -> **Note:** This SDK is in technical preview and may change in breaking ways. +> **Note:** This SDK is in public preview and may change in breaking ways. [![Build](https://github.com/github/copilot-sdk-java/actions/workflows/build-test.yml/badge.svg)](https://github.com/github/copilot-sdk-java/actions/workflows/build-test.yml) [![Maven Central](https://img.shields.io/maven-central/v/com.github/copilot-sdk-java)](https://central.sonatype.com/artifact/com.github/copilot-sdk-java) @@ -61,17 +61,17 @@ jbang https://github.com/github/copilot-sdk-java/blob/main/jbang-example.java ## Documentation & Resources -| Resource | Link | -|----------|------| -| **Full Documentation** | [github.github.io/copilot-sdk-java](https://github.github.io/copilot-sdk-java/) | -| **Getting Started Guide** | [Documentation](https://github.github.io/copilot-sdk-java/latest/documentation.html) | -| **API Reference (Javadoc)** | [javadoc.io](https://javadoc.io/doc/com.github/copilot-sdk-java/latest/index.html) | -| **MCP Servers Integration** | [MCP Guide](https://github.github.io/copilot-sdk-java/latest/mcp.html) | -| **Cookbook** | [Recipes](https://github.com/github/copilot-sdk-java/tree/main/src/site/markdown/cookbook) | -| **Source Code** | [github/copilot-sdk-java](https://github.com/github/copilot-sdk-java) | -| **Issues & Feature Requests** | [GitHub Issues](https://github.com/github/copilot-sdk-java/issues) | -| **Releases** | [GitHub Releases](https://github.com/github/copilot-sdk-java/releases) | -| **Copilot Instructions** | [copilot-sdk-java.instructions.md](https://github.com/github/copilot-sdk-java/blob/main/instructions/copilot-sdk-java.instructions.md) | +| Resource | Link | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| **Full Documentation** | [github.github.io/copilot-sdk-java](https://github.github.io/copilot-sdk-java/) | +| **Getting Started Guide** | [Documentation](https://github.github.io/copilot-sdk-java/latest/documentation.html) | +| **API Reference (Javadoc)** | [javadoc.io](https://javadoc.io/doc/com.github/copilot-sdk-java/latest/index.html) | +| **MCP Servers Integration** | [MCP Guide](https://github.github.io/copilot-sdk-java/latest/mcp.html) | +| **Cookbook** | [Recipes](https://github.com/github/copilot-sdk-java/tree/main/src/site/markdown/cookbook) | +| **Source Code** | [github/copilot-sdk-java](https://github.com/github/copilot-sdk-java) | +| **Issues & Feature Requests** | [GitHub Issues](https://github.com/github/copilot-sdk-java/issues) | +| **Releases** | [GitHub Releases](https://github.com/github/copilot-sdk-java/releases) | +| **Copilot Instructions** | [copilot-sdk-java.instructions.md](https://github.com/github/copilot-sdk-java/blob/main/instructions/copilot-sdk-java.instructions.md) | ## Contributing diff --git a/nodejs/README.md b/nodejs/README.md index 6d9870435..20e91adbf 100644 --- a/nodejs/README.md +++ b/nodejs/README.md @@ -2,7 +2,7 @@ TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC. -> **Note:** This SDK is in technical preview and may change in breaking ways. +> **Note:** This SDK is in public preview and may change in breaking ways. ## Installation diff --git a/python/README.md b/python/README.md index bc24e3c71..a023c6102 100644 --- a/python/README.md +++ b/python/README.md @@ -2,7 +2,7 @@ Python SDK for programmatic control of GitHub Copilot CLI via JSON-RPC. -> **Note:** This SDK is in technical preview and may change in breaking ways. +> **Note:** This SDK is in public preview and may change in breaking ways. ## Installation @@ -194,6 +194,7 @@ unsubscribe() ``` **Lifecycle Event Types:** + - `session.created` - A new session was created - `session.deleted` - A session was deleted - `session.updated` - A session was updated @@ -489,6 +490,7 @@ async with await client.create_session( ``` > **Important notes:** +> > - When using a custom provider, the `model` parameter is **required**. The SDK will throw an error if no model is specified. > - For Azure OpenAI endpoints (`*.openai.azure.com`), you **must** use `type: "azure"`, not `type: "openai"`. > - The `base_url` should be just the host (e.g., `https://my-resource.openai.azure.com`). Do **not** include `/openai/v1` in the URL - the SDK handles path construction automatically. @@ -583,14 +585,14 @@ async def on_permission_request(request: PermissionRequest, invocation: dict) -> ### Permission Result Kinds -| `kind` value | Meaning | -|---|---------| -| `"approved"` | Allow the tool to run | -| `"denied-interactively-by-user"` | User explicitly denied the request | +| `kind` value | Meaning | +| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| `"approved"` | Allow the tool to run | +| `"denied-interactively-by-user"` | User explicitly denied the request | | `"denied-no-approval-rule-and-could-not-request-from-user"` | No approval rule matched and user could not be asked (default when no kind is specified) | -| `"denied-by-rules"` | Denied by a policy rule | -| `"denied-by-content-exclusion-policy"` | Denied due to a content exclusion policy | -| `"no-result"` | Leave the request unanswered (not allowed for protocol v2 permission requests) | +| `"denied-by-rules"` | Denied by a policy rule | +| `"denied-by-content-exclusion-policy"` | Denied due to a content exclusion policy | +| `"no-result"` | Leave the request unanswered (not allowed for protocol v2 permission requests) | ### Resuming Sessions @@ -835,6 +837,7 @@ async with await client.create_session( ``` When `on_elicitation_request` is provided, the SDK automatically: + - Sends `requestElicitation: true` to the server during session creation/resumption - Reports the `elicitation` capability on the session - Dispatches `elicitation.requested` events to your handler