docs: add agent foundation migration paths

[tmoreton]

Human Overview

Add more migration guides

Description

The foundation page explained when to choose a framework but did not tell developers how to move from their current implementation. This adds distinct migration paths for direct model calls, custom agent loops, and existing frameworks, with staged guidance that preserves caller contracts and validates behavior during cutover.

Related Issues

Asana: Add migration guidance to the Strands foundation page

Documentation PR

Documentation-only change to the Choosing an Agent Foundation page.

Type of Change

Documentation update

Testing

Ran bash .agents/skills/pre-push/run-checks.sh docs, covering generated API docs, the full site build and broken-link check, docs typechecking, snippet typechecking, and docs tests.

• I ran hatch run prepare

Additional Details

Extended context (optional)

No additional details.

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Approve

Well-structured addition that fills a real gap: the foundation page now tells developers how to move to Strands, not just whether to. The staged, contract-preserving guidance is sound and the three paths are clearly differentiated.

Review Categories

• Links & anchors: Verified all 15 cross-references in the diff resolve (the .md→.mdx convention holds), and every anchor fragment (#invocation-limits, #cancellation, #from-a-hand-written-openai-loop, #from-the-openai-agents-sdk) matches a real heading in its target page.
• Terminology: Consistent with the terminology lock — tool calling, session management, model provider, structured output, agent loop, multi-agent, hooks, observability all use canonical terms.
• Voice/style: No em-dashes (one pre-existing em-dash was removed), no AI-tell or hedging phrases, active voice throughout.
• Structure: Each migration path answers one question and leads with the developer's goal; the concept-mapping table is a clean fit for the framework path.

Nicely done — the "keep the application boundary stable, compare behavior, keep a rollback switch" framing is advice that will hold up in production migrations.