Upgrading

Version relationship rules (all must hold simultaneously)

1. @ag-ui/client ↔ @copilotkit/runtime: the runtime pins an exact @ag-ui/client version. Your app’s @ag-ui/client must match it, or TypeScript breaks on HttpAgent shape differences (e.g. missing pendingInterrupts). After bumping CopilotKit, read the installed runtime’s package.json and align.
2. @copilotkit/* packages move together: react-core, react-ui, and runtime are released in lockstep — never mix versions. Check the lockfile actually resolved what package.json asks for.
3. agent-framework-* Python packages stay on one line: agent-framework-core, agent-framework-foundry, agent-framework-ag-ui, and the hosting package must be from compatible releases. Depend on agent-framework-core + specific extras, not the agent-framework meta-package (it drags optional dependencies that break Foundry remote image builds).
4. Hosting protocol version ↔ agent manifests: the Foundry hosting package implements a specific Responses protocol version; agent.yaml AND agent.manifest.yaml must declare the same version: or the agent fast-fails at startup with an explicit protocol-mismatch RuntimeError. Bump package and both manifests in one commit.
5. Deprecated package check: agent-framework-azure-ai was superseded by agent-framework-foundry. If the codebase still imports the old one, migrate before any other upgrade.

The upgrade loop

1. Inventory local workarounds first. Maintain a ledger mapping every patch/workaround in the codebase to the upstream issue it exists for (e.g. approval-forwarding code ↔ microsoft/agent-framework#6652; a previous_response_id guard ↔ #6851/#6828; a frontend fetch-bind shim ↔ the Illegal-invocation bug). An upgrade is the ONLY time these may be removed, and only when the issue is closed in the shipped version AND the regression test guarding that workaround passes without it. Never delete a workaround on a version bump alone.
2. Read what actually shipped. CopilotKit release notes are often empty auto-release stubs — diff the bundled .d.ts files between versions for API changes, and scan the issue tracker for regressions in your integration path (remote HttpAgent + frontend tools is a historically fragile combination).
3. Bump coherently per the rules above; reinstall; check the lockfile resolution.
4. Re-verify the full matrix, live — not just compile:
   • read/query path through the real UI;
   • frontend tools visible to the agent (explicitly — this has regressed before);
   • approve executes the gated tool exactly once; reject executes zero times;
   • follow-up turns after an approval do not re-execute (hitl.md hazard);
   • tool/approval cards still present after RUN_FINISHED, not just during streaming.
5. For hosted agents: restart azd ai agent run after a dependency change (the local runtime caches nothing between runs, but YOUR in-memory seed data resets — re-baseline before asserting), then redeploy and spot-check the deployed endpoint; local success does not prove the remote image builds (remote builds resolve dependencies independently — explicit pins avoid drift).

Known upstream issues to check on every upgrade

Statuses were accurate as of July 2026 — re-check before acting on them:

Foundry platform deadlines

Hosted agents deployed on the pre-April-2026 preview backend (azure-ai-agentserver-agentframework / -langgraph path) reached end of support on 2026-05-22 — anything still on that path must be redeployed on the current hosting packages, not upgraded in place. See the hosted-agent migration guide on Microsoft Learn (/azure/foundry/agents/how-to/migrate-hosted-agent-preview).