feat(showcase/ag2): migrate AG2 showcase integration to AG2 1.x - #7767

@NathanTarbert could you please trigger the CI run for this PR? Thanks!

Hi @tylerslaton @jpr5 @ranst91 @marthakelly @mme @NathanTarbert 👋

Friendly ping on this PR. All CI checks are green (50 passing, 2 skipped) and there are no merge conflicts. The last activity here was about a week ago.

Could one of you take a look and, if everything looks good, approve and queue it for merge? Happy to address any remaining feedback right away.

Thanks!

Hey @vvlrff, Apologies for the delayed response. I went through this properly, both the ag2 side and the four files outside it. All 50 checks are green now.

The thing I'd like to settle before this goes in is the loop caps. The old code set max_consecutive_auto_reply in twenty places, and this PR removes all twenty without putting anything back. Those limits weren't arbitrary: the comments deleted alongside them describe what happened without them, which was a tool loop producing enough log volume to hit the platform's rate limit, the service going unresponsive to health probes, and the watchdog killing it. AG2 1.x genuinely has no drop-in replacement, and you were right to say so in PARITY_NOTES.md. But the PR body's Known gaps list doesn't mention it, and that list is where a reviewer looks. There is a partial option: OpenAIResponsesConfig.max_tool_calls exists in 1.1.2 and isn't used anywhere here. It caps tool calls per response rather than turns in a loop, so it isn't the same guarantee, but on the agents that previously had the tightest limits it's a lot better than unbounded. Worth setting on those few, or at minimum moving the gap into the PR body so it's a conscious call rather than a surprise later.

On the aimock flag, the good news is that this isn't actually a conflict between integrations. The one file that breaks under strict mode is showcase/aimock/d6/mastra/shared-state-read.json, and the reason is visible in the file itself: it carries "copiedFrom": "langgraph-python", and its second leg has a comment saying "turn 2" while the field says "turnIndex": 0. The file it was copied from has no turnIndex on that leg at all. So it's a one-line fix in the fixture, not a reason for the flag to stay per-integration. Strict is also the honest default here, since the proxy path runs that way regardless. If you fix that line, this stops being a tradeoff and the flag can just be on.

Two things about the ag2 pin. requirements.txt asks for ag2[openai,ag-ui,mcp]>=1.1.2 with no ceiling, and the code carries patches written against 1.1.x internals. One of them injects a reasoning option because the 1.1.2 config object has no such field. That field exists in 1.2.1, which is what a fresh install resolves to today, so the patch is already doing nothing and its docstring already describes a version nobody installs. The other reaches into a private attribute on the request object. Neither is wrong today, but an unbounded floor plus private-API reach is the combination that breaks on someone else's machine and not yours. A ceiling, or a comment naming the exact versions each patch targets, would make that survivable.

Related, and this one CI can't catch for you. _usage_compat.py installs two patch targets. Only the second does anything. If you delete the first line the whole suite still passes, because the test calls the replacement function directly and never checks that installing it rebound anything. If you delete the second, every aimock-backed run dies partway through, after the text has already streamed to the user. A test that asserts the patch actually landed on the client would catch both directions.

Smaller, but worth a look. manifest.yaml now advertises reasoning support for tool-rendering-reasoning-chain, and that agent never asks for a reasoning summary. Only reasoning_agent.py gets that hook. Against aimock it looks fine because the fixture supplies the content, but against a real model that slot comes back empty and the manifest claim is false. Separately, the MCP ask tool is registered unconditionally and ends up in the chat agent's tool list, so the model can call it. That spins up a second model the demo doesn't intend to use and has no fixture for. The old prompt had a line telling the model not to, and this PR drops it.

On the big deletion, I think you made the right call and then undersold it. Removing the 390-line multimodal normalizer isn't just less code, it's better behavior: AG2 1.x produces real typed document inputs where the old path encoded PDFs as base64 image URLs. That's a capability gain, not parity. One detail that might matter for the bug you filed: 1.x drops the legacy binary part rather than converting it, which could be the actual source of the image-only-becomes-empty case rather than anything on the mock side. Worth confirming which before that report goes further.

Last one is the dependency list. requirements.txt dropped ag-ui-protocol and openai, but src/agents/_state.py still does from ag_ui.core import StateSnapshotEvent, and both src/agents/agent.py and src/agents/beautiful_chat.py still import openai. Those resolve today because ag2[openai,ag-ui] drags them in, so nothing breaks until ag2 changes what it depends on. reasoning_agent.py has the same shape in reverse: it imports httpx2, which is the right call since that's what AG2 1.x builds its client on, but the file declares httpx>=0.27.0 and nothing declares httpx2. Going the other way, pypdf>=4.0.0 is still pinned and the normalizer that used it is gone. While you're in there, roll_dice and roll_d20 disagree in one spot, which I think predates this PR but is a one-word fix.

Happy to talk through any of these. The loop cap is the only one I'd call blocking, and the mastra fixture line is the one that makes the cross-integration worry go away entirely.

Thanks for the thorough review, @NathanTarbert. Everything is addressed in c08e59f:

Loop cap (blocking). AG2 1.x does have a real replacement, just not as a config option. Middleware is instantiated per run, and on_llm_call can short-circuit the model. src/agents/_loop_cap.py allows at most N model calls per run. After that it ends the turn with a short text reply and no tool calls, which stops the loop. All 20 former max_consecutive_auto_reply sites have it back, with their old N (plus reasoning_agent). It counts model calls rather than auto-replies, so a single response that requests parallel tools counts once. That difference is noted in PARITY_NOTES.md. test_loop_cap.py checks that a scripted 10-round tool loop stops at 3.

aimock flag. You were right. I dropped the stray turnIndex: 0 on the second leg of aimock/d6/mastra/shared-state-read.json, and mastra:shared-state-read is now green with AIMOCK_STRICT_TURN_INDEX=1.

ag2 pin. Now ag2[openai,ag-ui,mcp]==1.1.2. Both patches name the version they target: _reasoning_summary.py (the reasoning.summary injection, which exists because 1.1.2's config has no reasoning field) and _usage_compat.py.

_usage_compat.py. Only the client-module binding is used in 1.1.2, so the no-op mappers rebind is gone. A new test asserts that after install_usage_compat() the client module calls the replacement.

Reasoning chain. The reasoning-summary config is now shared, and tool_rendering_reasoning_chain.py uses it, so the slot fills against a real model too. While checking this I found that the three reasoning cells were never in the manifest's features: list, so their probes had never run. They are listed now, and tool-rendering-reasoning-chain, reasoning-custom and reasoning-default are green on d6. ag2 also had no tool-rendering-reasoning-chain fixture at all. I added one, ported from langgraph-python (with roll_dice, which the shared probe expects). That was the roll_dice/roll_d20 mismatch.

MCP ask. AG2 1.1.2's MCPServer always registers it, and the runtime's mcpApps config has no per-server tool filter. So I restored a prompt line telling the model not to call it.

Dependencies. pypdf is removed. I did not add ag-ui-protocol, openai or httpx2 as separate lines. With ag2 pinned exactly, its extras fix which packages come in and their ranges (ag-ui-protocol>=1.0,<2, openai>=3.9.0,<4, and httpx2 via openai). They can only change when the ag2 pin moves, and I'd rather re-check them then than keep three pins that would have to move with it. Happy to add them if you'd prefer them explicit.

Multimodal. Agreed on the framing. I haven't yet confirmed whether the empty content comes from AG2 1.x dropping the legacy binary part. That is still open in Known gaps, and I'll check it before the aimock report goes further.

Verified: pytest 19/19 on Python 3.12 and 3.14; validate-parity, validate-pins (baseline ratcheted 24 → 23), validate-shared-symlinks and validate-fixture-tool-surface clean. d6 green on ag2 tool-rendering-reasoning-chain, reasoning-custom, reasoning-default, mcp-apps, agentic-chat, shared-state-read-write, subagents, and on mastra:shared-state-read.

Hey @vvlrff, it looks like showcase is failing.

@NathanTarbert could you please trigger the CI run for this PR? Thanks!

@vvlrff, yes, doing it now.

@NathanTarbert thanks for triggering the run! CI is green now (51 checks passed, 3 skipped), including showcase. Could you take another look and approve when you have a moment? Thanks!

Hey @vvlrff, no problem. On it!

Hey @vvlrff, thanks for working through all of that. The loop cap middleware is a nice way to get the old guarantee back, and the caps match what each agent had before.

One thing I'd like covered before this goes in. The docstring in _loop_cap.py says the count resets every run because AG2 creates middleware per run. That's the key property here. If it ever stops being true, an agent that is defined once at module level would hit its cap once and then answer every request after that with the limit message. Both tests in test_loop_cap.py call ask a single time, so they wouldn't notice. Could you add a test that calls ask twice on the same agent and checks that the second run gets its full allowance?

Also, could you refresh the Known gaps section in the PR description? It still lists the mastra:shared-state-read strict-mode failure and the roll_dice/roll_d20 mismatch, and both of those are fixed now. Whoever merges this will read that list, so it's worth keeping it accurate.

@NathanTarbert thanks! Added test_cap_resets_between_runs_of_the_same_agent, which calls ask twice on the same agent and checks that both runs get the full allowance. It fails if the count leaks across runs. I also removed the two fixed items from Known gaps.

Thanks @vvlrff, that test covers it. Nothing else from me on this one.