pip install --upgrade agency-swarm still installs 1.11. Pass --pre and the version, as shown above.
1. Raise your dependency pins
If your project pins any of these packages, raise the pins to these ranges:
Agency Swarm pins the OpenAI Agents SDK (
openai-agents) to one exact version. Do not pin a different one in your project. If your code calls the OpenAI or MCP SDKs directly, read their own migration notes too.
2. Install LiteLLM as an extra
LiteLLM is no longer installed by default. Without it,from agency_swarm import LitellmModel raises an ImportError that explains the fix.
Current LiteLLM releases still declare openai<3, so a plain pip install "agency-swarm[litellm]" installs LiteLLM 1.83.0, the newest release that allows openai 3. To get the current LiteLLM:
- uv
- pip
Add this to your
pyproject.toml, then run uv add "agency-swarm[litellm]":3. Add packages your own code imports
Agency Swarm no longer installsrequests, types-requests, termcolor, griffe or httpx for you. If your code imports one of them, add it to your own dependencies.
4. Check agents that use the default model
The default model is nowgpt-6-luna with reasoning effort medium and verbosity low. Before, it was gpt-5.6-luna with effort none. Agents without a model may answer differently, cost more and take longer.
gpt-6-luna rejects temperature and top_p. An agent that sets them without a model now gets an error from the API. To keep the old behavior, set the model and settings yourself:
5. Know that long conversations are compacted
For model names that start withgpt-, or with o and a digit, Agency Swarm now asks the OpenAI API to compact long conversations. Compaction starts at 90% of the model’s context window when the Agents SDK knows it, otherwise at 240,000 tokens. Saved history is replayed from the latest compaction, so later turns send fewer tokens. When every agent in the agency runs on an OpenAI model, the /compact command in the terminal demo now uses OpenAI’s compaction endpoint too.
To turn compaction off for an agent, for example on an endpoint that serves a gpt-* name but rejects the setting:
context_management on ModelSettings, not in extra_args:
Agent, the old extra_args form still works: Agency Swarm then skips its own default. On a RunConfig(model_settings=...) passed to get_response() it does not. The request would carry the setting twice, so every run fails with responses.create() got multiple values for keyword argument 'context_management'.
Your stored history can start at the latest compaction. Each conversation (the user thread, and each pair of agents that talk to each other) is replayed from its own latest compaction item. Items of that conversation stored before it are never sent to the model again. So the chat_history you send to run_fastapi, and the messages your load_threads_callback returns, can drop them. Keep items marked "message_origin": "compaction_retained" right before the compaction item: they belong to it.
6. Import Runner from agency_swarm
Agency Swarm no longer patches the Agents SDK. agents.Runner now behaves like the stock SDK, so it does not apply your agents’ system_reminders. Use agency_swarm.Runner instead. To save and restore a run, use run_state_to_json and run_state_from_json from agency_swarm.
7. Return AuthorizationCodeResult from an OAuth callback_handler
If you pass your own callback_handler to MCPServerOAuth, it must now return an AuthorizationCodeResult instead of a (code, state) tuple. MCP 2 rejects a callback without iss when the authorization server says it supports one, so pass it through. run_fastapi and the default local handler already do this for you.
8. Pass a host to reach the browser demos from another machine
agency.copilot_demo() and RealtimeDemoLauncher.start() now listen on 127.0.0.1, so only your own machine can open them. Pass host="0.0.0.0" when you run them in Docker or on a remote server.
run_fastapi(), agency.run_fastapi(), run_mcp() and run_realtime() still listen on 0.0.0.0. When they do and APP_TOKEN is not set, they now log a warning that anyone who can reach the port can call your agency.
9. Replace deprecated APIs
Agency(user_context=...) and agency.user_context are deprecated. They still work but emit a DeprecationWarning. Pass state per run with context_override, as shown in Agency Context.