On this page
At Ignite on Tuesday, Microsoft announced Copilot SDK 2.0: the SDK formerly called the GitHub Copilot SDK, now generally available, rebuilt around a native Rust runtime and offered in six languages. The Book of News describes it as the same harness technology Microsoft and GitHub run in production, aimed at enterprises building agents. It follows on from my Book of News review: a vendor harness is exactly what my September article, What an Agent Harness Needs Before Production, said you need, and exactly what you should not take on trust.
So this article runs the eleven bad days from that article against Copilot SDK 2.0, using the Python package published on Wednesday, microsoft-copilot-sdk 2.0.1. As in One Agent, Three Frameworks, a scripted model stands in for a real one, so every misbehaviour is exact and repeatable and nothing is billed. Each scenario runs twice: with the configuration from the SDK’s README quick start, and with a hardened configuration that uses the SDK’s own controls plus the minimum of code around them.
The short version: the runtime handled five of the eleven on its own, and handled them well. The other six, including a runaway loop, a refund triggered by text in a tool result, and generated code reading a secret, went wrong with the quick-start configuration and right with the hardened one. Copilot SDK 2.0 is a capable harness. Its defaults are a developer’s defaults.

What Copilot SDK 2.0 is
The SDK gives your application programmatic access to the agent runtime behind Copilot CLI: the model loop, built-in tools, permissions, hooks, sessions and context management. Version 2.0 changes where that runtime lives. All six SDKs now load the native Rust runtime into your application’s process by default and talk to it over JSON-RPC in memory, instead of starting a separate CLI process. The repository’s own migration guide adds the important caveat in a warning box: in-process hosting is not a sandbox and provides no crash isolation. A child-process or standalone runtime server is still available when you need that boundary.
| Item | What I found |
|---|---|
| Python package | microsoft-copilot-sdk 2.0.1 on PyPI, uploaded 18 November 2026; requires Python 3.11+ |
| .NET package | Microsoft.Copilot.SDK 2.0.0 on NuGet |
| Native runtime | Version 1.0.114, downloaded on first use or with python -m copilot download-runtime --in-process; about 196 MB on Linux x64, verified against the release’s SHA256SUMS |
| Client modes | coding-agent (Copilot CLI-like defaults) or empty (opt into each feature explicitly) |
| Models | Copilot’s own, or bring your own key: OpenAI, Azure OpenAI and Foundry, Anthropic, Google, or any OpenAI-compatible endpoint |
The test
The agent is a small order-support assistant with five tools: look up an order (whose customer note can carry text), track a shipment through a carrier API that fails twice before working, export a 2 MB order history, check stock through a service that takes six seconds, and refund an order, which moves money. A scripted endpoint that speaks the OpenAI chat-completions protocol plays the model. The SDK reaches it as a bring-your-own-key provider, with Copilot inference switched off, so the test needs neither a GitHub sign-in nor a model key.
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#EBF8FF','primaryTextColor':'#0F172A','primaryBorderColor':'#0078D4','lineColor':'#334155','clusterBkg':'#F8FAFC','clusterBorder':'#CBD5E1','edgeLabelBackground':'#FFFFFF','nodeTextColor':'#0F172A'}}}%%
flowchart TD
A["Test runner, Python 3.12"] --> B["microsoft-copilot-sdk 2.0.1"]
B -->|"JSON-RPC in memory"| C["Native Copilot runtime 1.0.114, in process"]
C -->|"BYOK, OpenAI chat completions"| D["Scripted model: misbehaves on cue"]
C -->|"tool calls"| E["Shop tools: orders, carrier, export, stock, refund"]
C -->|"built-in bash, generated-code scenarios"| F["Shell on the host, or in the runtime sandbox"]
style D fill:#FFF3E0,stroke:#FF9900,stroke-width:2px,color:#232F3E
style E fill:#F0FFF4,stroke:#1D8102,stroke-width:2px,color:#145202
style F fill:#FEF2F2,stroke:#D13212,stroke-width:2px,color:#991B1BThe two configurations differ only in how the SDK is set up. Defaults is the README quick start: mode="coding-agent", PermissionHandler.approve_all and tools written with @define_tool. Hardened uses mode="empty" with a per-tenant storage directory and an explicit tool allow-list, a permission handler that gates refunds and commands, a turn budget that aborts the session, tool handlers wrapped with a timeout, retries and a size cap, and a refund keyed on the business operation. The generated-code scenarios, which need the built-in shell, use the runtime’s sandbox with the secret masked.
Results

| Bad day | Quick-start defaults | Hardened |
|---|---|---|
| Model never stops calling a tool | 585 model calls in 30 s, and still running after the wait ended | Stopped by the budget after 12 model calls |
| Wrong argument name and type | Told order_id: Field required, corrected, answered | The same |
| A tool that does not exist | Told it does not exist, with a list of 18 built-in tools | Told it does not exist, with the five tools the agent has |
| A tool that fails twice, then works | Generic failure text, no host name; the model retried twice | The tool retried with backoff; the model saw one result |
| A tool that returns 2 MB | 838 characters sent; the full 2 MB written to the OS temp directory | 4,065 characters sent; capped in the tool |
| A tool that takes 6 seconds | Waited | Gave up after 1 s and said so |
| An instruction hidden in a tool result | Refunded 150.00 on an order nobody mentioned | Refund rejected by the permission gate |
| Generated code reads the environment | Fake payments key in the output | Masked value in the output |
| Generated code allocates 1 GB | Allocated | Allocated (the sandbox sets no memory limit) |
| Generated code opens a connection | Connected | Connection failed inside the sandbox |
| Process dies right after a refund | Resumed from the journal; refund paid twice | Resumed; refund paid once |
The generated-code results in the hardened column come from an Ubuntu 24.04 machine with Bubblewrap, slirp4netns and iproute2 installed. In Cloud Shell, where they are not available, the sandboxed commands were refused rather than run without the sandbox.
What the runtime handled
- Bad arguments and unknown tools came back to the model as plain, correctable messages, and the model fixed its call in the next turn. With Pydantic parameters, validation happens before your handler runs.
- Exceptions did not leak. The carrier API’s exception named an internal host and a connection pool. The model saw only that the tool failed. In One Agent, Three Frameworks, the same kind of exception ended the run in two of three frameworks, carrying the host name out with it.
- Large results were not pushed into the context. Anything over 20,480 bytes is written to a file and the model gets a short notice. That protects the context window, but the file lands in the OS temp directory, outside the tenant’s storage, and stays there until the session disconnects. Set
tools.large_output.output_directory, or cap results in the tool. - A crash did not lose the session. The runtime keeps a journal on disk. After the process died mid-refund, a new process resumed the session, and the runtime told the model that the tool “was interrupted before a result was recorded” and that its effects “may be absent, partial, or already complete”. It did not re-run the refund itself.
- Safe refusals by default. With no permission handler at all, every tool call was refused as “no one could answer”. In
emptymode the client refuses to start without per-tenant storage, and every session must list the tools it allows.
What you have to add
A budget that stops the session
The runtime has no turn limit for a model you bring yourself. The only session limit in the documentation is an AI Credits budget, execution.limits.max_ai_credits, with a minimum of 30; with a BYOK model it did not stop 613 model calls in 20 seconds. More surprising, send_and_wait(timeout=60) only stops waiting. After it raised, the session carried on calling the model until the test called session.abort(). The hardened configuration counts turns from the session’s events and aborts:
@dataclass
class Budget:
max_turns: int = 12
turns: int = 0
stopped: bool = False
def attach(self, session) -> None:
def on_event(event) -> None:
if event.type.value == "assistant.turn_start":
self.turns += 1
if self.turns > self.max_turns and not self.stopped:
self.stopped = True
asyncio.get_running_loop().create_task(session.abort())
session.on(on_event)If your service calls send_and_wait with a timeout and returns an error to its caller when it fires, the agent may still be running, calling the model and your tools. Always follow a timeout with session.abort(), and alert on it.
An approval gate for writes
Custom tools go through the same permission flow as the built-in ones, as custom-tool requests. The quick start answers all of them with approve_all, which is how an instruction in a customer note became a 150.00 refund on another order. The gate below approves reads, rejects commands, and lets a refund through only for an order the user named:
@dataclass
class Approver:
allowed_orders: set[str] = field(default_factory=set)
def __call__(self, request, _invocation):
match request:
case PermissionRequestCustomTool(tool_name="refund", args=args):
if (args or {}).get("order_id") in self.allowed_orders:
return PermissionDecisionApproveOnce()
return PermissionDecisionReject(
feedback="Refunds need approval from a person; this one was not approved. Do not retry.")
case PermissionRequestShell():
return PermissionDecisionReject(feedback="This agent does not run commands.")
case _:
return PermissionDecisionApproveOnce()The rule here is a stand-in. In production the decision belongs to something the model cannot influence: a person, or a policy service that knows who the user is and what they asked for.
Timeouts, retries and size limits in the tool
The runtime waited six seconds for the stock service and would have waited longer, and it did not retry the carrier API; the model did. Both belong in the tool, where you know which errors are transient. The hardened handlers share one wrapper:
async def guarded(name, call, *, retries=2) -> ToolResult:
for attempt in range(retries + 1):
try:
text = as_text(await asyncio.wait_for(call(), TOOL_TIMEOUT_S))
if len(text) > RESULT_CAP:
text = text[:RESULT_CAP] + f"... [cut at {RESULT_CAP} of {len(text)} characters]"
return ToolResult(text_result_for_llm=text, result_type="success")
except asyncio.TimeoutError:
return ToolResult(text_result_for_llm=f"{name} did not answer within {TOOL_TIMEOUT_S:.0f} s.",
result_type="timeout")
except Transient:
if attempt == retries:
break
await asyncio.sleep(0.05 * 2 ** attempt + random.uniform(0, 0.05))
except Exception:
break
ref = uuid.uuid4().hex[:8]
log.exception(json.dumps({"event": "tool_failed", "tool": name, "ref": ref}))
return ToolResult(text_result_for_llm=f"{name} failed (reference {ref}). Do not retry.", result_type="failure")One API detail cost me a run: a low-level Tool handler must return a ToolResult. Returning a plain string fails the call. Handlers declared with @define_tool can return either.
A sandbox for generated code, and its limits
In coding-agent mode the model gets a bash tool that runs on the host, in the application’s environment. With the quick start’s approve_all, generated code printed the fake payments key from that environment, allocated a gigabyte and connected to a local port. The runtime has a sandbox, permissions.sandbox, built on Bubblewrap on Linux, with filesystem rules, a network policy and credential masking:
sandbox = SandboxConfig(
enabled=True,
credentials=SandboxCredentialsConfig(
env_vars={"PAYMENTS_API_KEY": SandboxMaskedEnvVar(inject_hosts=["payments.example.com"])}),
)
session = await client.create_session(
model=model, permissions={"on_request": approver, "sandbox": sandbox}, **byok(base_url))| Generated code | No sandbox | Sandbox, default policy | Sandbox with the key masked |
|---|---|---|---|
| Reads the environment | Key printed | Key still printed | copilot_mask_… printed |
| Allocates 1 GB | Allocated | Allocated | Allocated |
| Opens a connection | Connected | Failed | Failed |
Three things to take from that. The sandbox fails closed: without Bubblewrap, slirp4netns and ip, sandboxed commands are refused, which is what happened in Cloud Shell. Network isolation is on by default, but secret masking is not: it is a separate list of variables, each with the hosts allowed to receive the real value. And there is no memory limit, so a container or cgroup limit around the runtime is still needed. For an agent like this one, which has no reason to run code, the better answer is not to give it a shell: in empty mode, bash is not available unless you add it.
Idempotency the service enforces
The crash scenario shows the boundary between harness and service. The runtime did its part: it told the model the refund’s outcome was unknown instead of pretending it had failed. The scripted model then did what a cautious real model might, and asked for the refund again, under a new call id. With the ledger keyed on the call id, that paid twice. With the ledger keyed on the business operation, one refund per order per conversation, it paid once. The runtime cannot know that two calls are the same payment; only the service behind the tool can.
The quick start approves every tool call, runs commands on the host and loads the runtime into your process, which the SDK’s own guide says is not a sandbox. That is reasonable for a coding assistant on a developer’s machine and wrong for a service handling customer data, payments or health records. Start from mode="empty", give each tenant its own storage directory, list the tools each session may use, put an approver in front of every write, keep large outputs out of shared temp directories, and run the runtime in its own process or container if a crash must not take your service down.

Decision framework
| If your agent | Copilot SDK 2.0 gives you | You still add |
|---|---|---|
| Only reads, for one user | Argument validation, unknown-tool handling, safe tool errors, large-output handling | A turn budget that aborts, and timeouts in the tools |
| Calls services that fail or stall | Error text that does not leak | Retries with backoff and a per-call timeout in each tool |
| Reads documents, tickets or customer notes | A permission flow that sees every custom-tool call | An approver for every write that the model does not control |
| Changes money or records | A journal that survives a crash and an honest “interrupted” result | An idempotency key the service enforces |
| Runs generated code | A sandbox with network isolation and opt-in secret masking | A memory limit, and Bubblewrap on the hosts |
| Serves many tenants | empty mode, per-tenant storage, explicit tool lists | Separate runtime processes where crash isolation matters |
Compared with the 366 lines of harness code in the September article, both configurations here fit in 213 lines of configs.py, most of them the tool definitions. The runtime carries the loop, the validation, the error handling, the journal and the sandbox. What it leaves to you is the part that depends on your domain: when to stop, who approves, what counts as the same payment, and how long a tool may take.
The sample was run with Python 3.12, microsoft-copilot-sdk 2.0.1 and native runtime 1.0.114, in process, with a scripted OpenAI-compatible model reached through the SDK’s bring-your-own-key provider and Copilot inference switched off. All eleven scenarios ran under both configurations in Azure Cloud Shell (the screenshot) and on an Ubuntu 24.04 machine with Bubblewrap, slirp4netns and iproute2, where the sandbox scenarios ran; the results file in the repository records both. The 11 tests in the repository pass in about 100 seconds. Behaviour and options are from the SDK’s repository documentation, its v2 migration guide and the package source. No real model was used, so these results describe the harness, not any model’s judgement. The payments key in the generated-code scenarios is fake.
Key takeaways
- Copilot SDK 2.0 handled five of the eleven bad days on its own: bad arguments, unknown tools, leaky exceptions, oversized results and a crash mid-call.
send_and_wait’s timeout stops waiting, not the agent; the only built-in limit did not stop a BYOK runaway. Abort the session from your own budget.- The quick start’s
approve_allpaid a refund that came from text in a tool result. Put an approver the model does not control in front of every write. - The sandbox blocks the network and fails closed, but secret masking is opt-in and there is no memory limit.
- Start production agents from
mode="empty", with per-tenant storage, explicit tools, timeouts in the tools and an idempotency key in the service.
Have you put Copilot SDK 2.0 in front of real users yet, and which of these did you have to add? Tell me in the comments.
The complete sample for this article is on GitHub: nithinmohantk/blog-samples-working-repo/copilot-sdk-harness-test. Clone it with git clone https://github.com/nithinmohantk/blog-samples-working-repo.git and open the copilot-sdk-harness-test folder. Its README says how to run it and what has been verified.
Glossary
- Agent harness
- The code around a model that runs its tool loop and enforces limits, validation, approvals and recovery.
- Microsoft Copilot SDK
- The SDK, formerly the GitHub Copilot SDK, that embeds the Copilot agent runtime in an application.
- In-process hosting
- Loading the native runtime into the application’s own process; the 2.0 default, with no crash isolation.
- BYOK
- Bring your own key: using your own model provider instead of Copilot’s models.
- Scripted model
- A stand-in endpoint that returns pre-written replies, so a test can make a model misbehave on cue.
- coding-agent mode
- The client mode with Copilot CLI-like defaults, including built-in file, shell and web tools.
- empty mode
- The client mode in which storage, tools and features are opted into explicitly.
- Permission handler
- The callback that approves or rejects each tool call before it runs.
- Runaway loop
- A model that keeps calling tools without ever answering.
- Idempotency key
- A value that lets a service recognise a repeated request and perform it only once.
- Session journal
- The runtime’s on-disk record of a session, used to resume after a restart or crash.
- Bubblewrap
- A Linux tool for running processes in isolated namespaces; the Copilot runtime’s sandbox uses it.
- Credential masking
- Replacing a secret in a sandboxed process’s environment with a placeholder that only allowed hosts can exchange for the real value.
References & Further Reading
- → Microsoft Ignite 2026 Book of News— The Copilot SDK 2.0 announcement
- → microsoft/copilot-sdk on GitHub— Source, documentation and samples for all six languages
- → SDK v2 breaking changes— In-process hosting by default, explicit modes and the migration from 1.x
- → Bring your own key— Provider types and configuration
- → The agent loop— Turns, tool calls and parallel execution
- → Session limits— The AI Credits budget
- → microsoft-copilot-sdk on PyPI— The Python package used here
- → What an Agent Harness Needs Before Production— The eleven bad days and the checklist
- → One Agent, Three Frameworks— The scripted-model method, applied to three frameworks
Discover more from C4: Container, Code, Cloud & Context
Subscribe to get the latest posts sent to your email.