01 · What changed
We changed the framework, not the product.
Creating an agent with the new framework was easy. Making it behave like the existing product was the real work.
Claude Agent SDKOld agent framework
→
LangChain Deep AgentsNew agent framework
Must stay the same: tools · messages · memory · interruptions · results
The old framework did much more than call a model. It managed tool calls, conversation history, images, user questions, errors, and final results. Every one of those behaviors needed a clear replacement.
We kept the shared tool system underneath both frameworks. We also kept model-specific code separate, so Claude could remain the first model without making future model changes difficult.
Simple ruleKeep the experience the same for the user. Change only how the agent runs behind the scenes.
02 · Scope
The migration came down to ten decisions.
01
One agent run
How to connect a request, its tool calls, interruptions, and final answer.
02
Conversation memory
How to replay older messages and keep one framework for the whole conversation.
03
Cost tracking
How to count model usage and keep billing accurate.
04
Safety limits
How long an agent can run, when it retries, and what happens after an error.
05
Images and questions
How the agent sees a rendered image and pauses to ask the user something.
06
Documents
How the agent searches and reads documents without direct file or shell access.
07
User information
How brand details and saved user preferences reach the agent.
08
Helper agents
What smaller agents can do and which instructions and tools they receive.
09
Tests
How to prove that tests are actually measuring the new framework.
10
The final switch
When to make the new framework the default and remove the old one.
Writing these decisions down made the project easier to split, build, and test.
03 · What we kept
We reused useful parts and removed old assumptions.
Tool systemBoth frameworks call the same shared tools through a small adapter.We did not rebuild every integration.
No shell or local filesThe new agent does not get broad computer access. Document search, reading, and other actions become clear tools.Each capability is limited and easier to control.
InstructionsThe system adds only the instructions that are useful for the current task directly to the prompt.No temporary instruction files are needed.
ImagesThe agent can see a rendered image during the current turn, but old images are not repeatedly added to later prompts.This prevents image costs from growing every turn.
Pausing the agentWhen the agent needs the user or must stop, it exits the current run cleanly and waits.No second cancellation system is needed.
Model choiceClaude ships first, but model setup and usage tracking stay separate from the rest of the agent.Another model can be added without repeating the migration.
04 · What came first
First, make the new agent visible to the tests.
The first important job was recording each tool call, event, interruption, and result from the new framework. Without that record, a test could pass simply because it saw no activity.
Record one complete agent run
Memory + history
Errors + time limits
Images + user questions
Documents + user information
Cost tracking
Helper agents
Evaluation
Full test suite → make new framework the default
Once tests could see a complete run, several teams could close the remaining gaps in parallel.
05 · How we switched
The rollout stayed easy to reverse until the end.
01
Add a feature flagLet selected users try the new framework while the old one remains available.
safe
02
Choose once per conversationA conversation cannot switch frameworks halfway through.
stable
03
Record everything tests needMake tool calls and results visible on the new path.
testable
04
Close the important gapsFinish memory, errors, images, documents, and user information.
parallel
05
Run the full test suiteThe new path must pass the same product checks.
verified
06
Make the switchSet the new framework as the default, then delete the old path.
simpler
The feature flag was temporary. Keeping both systems forever would double the code and make future changes harder.
06 · Key lessons
The best result was a cleaner system, not just a new framework.
List behavior before writing code.Understand everything the old framework provides before replacing it.
Share the important parts.Keep tools and product rules outside the framework-specific code.
Do not copy old limitations.A new framework does not need to recreate every feature of the old one.
Make sure tests can see the new path.A passing test means little if it observed no tool calls or results.
Name acceptable gaps.Decide which smaller features may arrive later instead of finding out during launch.
Remove the old path.The migration is finished only when the temporary switch and duplicate code are gone.
Bottom lineThis was not one choice between two frameworks. It was ten smaller choices about how the product should work.