NetFabric/intelligentium / .agents/skills/copilot-sdk
copilot-sdk
VerifiedEmbed the GitHub Copilot agent runtime into your own application using the Copilot SDK. USE FOR: CopilotClient/createSession setup, streaming responses, custom tools, permission handlers, hooks (pre/post-tool-use, session-start), custom agents and sub-agent delegation, MCP servers, skill and plugin directories, session persistence, fleet mode, steering/queueing, calling the SDK from skill scripts/ to run one bounded non-deterministic AI step inside an otherwise deterministic script, and choosing an auth/deployment path (CLI setup, backend services, multi-tenancy, GitHub OAuth, BYOK). Covers Node.js/TypeScript (@github/copilot-sdk), Python (github-copilot-sdk), Go (github.com/github/copilot-sdk/go), Rust (github-copilot-sdk crate), .NET (GitHub.Copilot.SDK), and Java (copilot-sdk-java). DO NOT USE FOR: authoring SKILL.md files consumed by VS Code Copilot (use create-skill instead); using the Copilot IDE extension or chat UI directly; general LLM/chat API integration unrelated to the Copilot SDK.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| references/advanced-features.md | markdown | 4.4 KB |
| references/core-session-api.md | markdown | 4.4 KB |
| references/language-quickstarts.md | markdown | 3.3 KB |
| references/setup-and-auth.md | markdown | 3.7 KB |
references/core-session-api.md
View on GitHub# Core Session API
## Client and session lifecycle
1. Construct a `CopilotClient` (optionally with `connection`, `mode`, auth options).
2. `start()` the client (spawns/attaches to the `copilot` CLI); some languages start implicitly on first use.
3. `createSession(config)` — one session per conversation.
4. Send prompts; read replies or subscribe to streaming events.
5. `stop()` the client / `disconnect()` the session when done (or use `await using` / `try-with-resources` / context managers where the language supports it).
## Session config fields
| Field | Purpose |
|---|---|
| `model` | Model ID, or `"auto"` to let the runtime choose |
| `streaming` | Emit incremental `*_delta` events as the reply is generated |
| `tools` | Custom tools available to this session (see below) |
| `availableTools` | Restrict which built-in/custom tools a session may use (multi-tenant safety) |
| `onPermissionRequest` | Callback deciding whether a tool call is allowed |
| `customAgents` | Sub-agent definitions (see advanced-features.md) |
| `mcpServers` | MCP server configs (see advanced-features.md) |
| `skillDirectories` | Directories of `SKILL.md` files to load into context |
| `hooks` | Lifecycle interceptors (see advanced-features.md) |
| `gitHubToken` | Per-session GitHub identity (multi-tenant deployments) |
| `sessionId` | Explicit ID for resuming/looking up a session later |
## Sending messages
| Method | Behavior |
|---|---|
| `sendAndWait(prompt)` | Sends and blocks until the final assistant reply; simplest for one-shot use |
| `send(prompt)` | Fire-and-forget; returns a message ID immediately, reply arrives via events |
| `send(prompt, { mode: "immediate" })` | **Steering** — injects into the turn the agent is currently running |
| `send(prompt, { mode: "enqueue" })` | **Queueing** — buffers the message until the current turn finishes |
Use `send` (not `sendAndWait`) whenever you also subscribe to streaming events, since `sendAndWait` already waits for completion internally.
## Permission handling
Every tool call (built-in or custom) can require a permission decision. Provide `onPermissionRequest` (or a hook's `permissionDecision` output) returning one of:
| Decision kind | Effect |
|---|---|
| `approve-once` | Allow this single call |
| `approve-for-session` | Allow this tool for the rest of the session, no more prompts |
| `approve-for-location` | Allow this tool for a specific path/scope |
| `approve-permanently` | Persist approval beyond the session (stored config) |
| `deny` | Reject the call |
| `ask` | Defer to a human-facing prompt (interactive CLIs) |
For unattended/server use, most samples pass an "approve all" convenience (`PermissionHandler.approve_all` in Python, `PermissionHandler.ApproveAll` in .NET/Java, `ApproveAllHandler` in Rust) — only safe when `availableTools` already scopes what the session can call.
## Streaming events
Every action emits a session event with a common envelope: `id`, `timestamp`, `parentId` (links to the previous event), `agentId` (set for sub-agent events), `ephemeral` (transient vs. persisted/replayable), `type`, `data`.
| Event type | Meaning |
|---|---|
| `assistant.message_delta` | Ephemeral streaming text chunk; accumulate for full content |
| `assistant.message` | Persisted, complete assistant message |
| `assistant.turn_start` / `assistant.turn_end` | Bounds of one agent turn |
| `tool.execution_start` / `tool.execution_complete` | A tool call began/finished |
| `session.idle` | Session finished processing and is waiting for input |
| `subagent.completed` | A custom-agent sub-agent finished (see advanced-features.md) |
Subscription methods: `session.on(handler)` for all events; `session.on(eventType, handler)` for one type (Node.js/TS only, with narrowed payload types); `session.subscribe()` returns a channel/stream to filter manually (Rust). All return an unsubscribe handle/function except where the language uses `try/finally`-style disposal.
## Custom tools
Define a tool with a name, JSON-schema parameters, and a handler; pass it in `tools` on session creation. Node.js uses a `defineTool(name, { description, parameters, handler })` helper; other languages provide an equivalent builder or attribute/derive macro (Rust uses `schemars`-derived structs, Java/.NET use POJOs/records with the SDK's tool-definition API). The model calls the tool by name with JSON args; your handler runs and its return value is sent back as the tool result.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |