feat(response): inject json schema into the last message instead of system prompt

[Rubikoid]

Why are these changes needed?

I ran into the following scenario: I had a warmed-up session with a model that was supposed to respond with a structured response on .ask.

My provider didn't support "full, via API" schema passing, and PromptedSchema inserted the schema into the system prompt - as a result, the model couldn't make sense of its own prior history and produced JSON poorly (only from the second or third attempt).

After switching to LastMessagePromptedSchema, the model started producing JSON on the first or second try.

I'm not sure this is the most elegant or correct implementation — if it's not, let's refine it together.

Related issue number

Did't find corresponding.

Checks

• I've included any doc changes needed for https://docs.ag2.ai/. See https://docs.ag2.ai/latest/docs/contributor-guide/documentation/ to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

AI assistance

• I understand the changes in this PR and can explain them in my own words.
• I have verified that the PR description accurately reflects the actual diff.
• If AI assistance was used, I reviewed, tested, and validated the generated code/text before submitting.

[CLAassistant]

All committers have signed the CLA.

[genisis0x]

The motivation makes sense — for providers without native structured output, and especially without a usable system prompt, putting the schema instruction near the generation boundary is a real improvement, and the inject_to / LastMessagePromptedSchema opt-in keeps the default behavior intact. _inject_last_message_prompt is also nicely done: it rebuilds the list and the ModelRequest copy instead of mutating, and no-ops safely. Multi-provider tests (bedrock/zai/agent/prompted) are a good touch.

Two things I'd look at, both around the "last message" semantics:

1. It targets the last ModelRequest, not literally the last event. In a plain .ask with no tools that's the same thing, so it works. But once there are tool round-trips, the most recent ModelRequest (the user turn) can sit several events back — behind ToolResultsEvents and prior ModelResponses — so the schema instruction is no longer adjacent to where the model generates. Since the whole point is "the model pays more attention to the end of the conversation," it might be worth appending a fresh trailing turn at generation time rather than augmenting the last user request, so the instruction is always last. At minimum, a note in the docstring that "last message" means "last user request" would avoid surprise.

2. Silent no-op when there's no ModelRequest. _inject_last_message_prompt returns messages unchanged if it finds no ModelRequest, which means the schema guidance is dropped entirely for that call (rather than, say, falling back to the system prompt). That's an easy corner to hit with a history that starts from a non-request event. Consider falling back to system injection (or emitting a warning) in that branch, and adding a test for the no-ModelRequest case to lock whichever behavior you choose.

Minor: appending the instruction as a TextInput onto the existing user ModelRequest.parts merges it into the user's own message. That's probably fine, but a one-line comment on why it's merged into the last request vs. sent as a distinct message would help the next reader.

[Solaris-star]

Good fix for a real gap. Providers that don't support API-level schema passing (Bedrock with certain models, some local providers) were stuck with system-prompt injection, which pollutes the system message and breaks warmed-up sessions.

Observations:

1. schema_location enum: system (default, backward compat) vs last_message is a clean API. The PromptedSchema change to support both injection points is well-scoped.

2. Agent.ask() integration: the +29 lines in agent.py thread the schema_location through to the response handler. The proto change (ResponseSchema.location) keeps it typeable.

3. Test coverage: +125 in test_prompted.py and +78 in test_response_schema.py — both injection paths are covered, including the edge case where the last message is an assistant message (schema goes to a new user turn).

4. Docs: the structured_output.mdx update shows both modes with examples. Good.

5. One edge case: if the conversation is empty (no messages), where does last_message injection go? Falls back to system? The test suite should cover the empty-history case.

LGTM with the empty-history edge case noted.