Python: preserve roles in Claude prompt history

[Jose Alvarez (jpalvarezl)]

Motivation & Context

ClaudeAgent currently flattens incoming messages into a single prompt without preserving their roles. In multi-agent workflows, this makes user input and previous agents' responses indistinguishable. This change retains role information and explicitly frames the supplied transcript as conversation history for the receiving agent's assigned task.

Description & Review Guide

• What are the major changes? Update _format_prompt() to prepend a conversation-history explanation and label each message with its role, while leaving a single user message unchanged. Add regression coverage for mixed-role history, messages from named and unnamed agents, and a single assistant message. Add a documented SequentialBuilder sample that passes a grammar inspector's output to a second Claude agent. Broaden the function_invocation_kwargs and client_kwargs annotations from dict to Mapping in the run() signatures.
• What is the impact of these changes? Claude receives explicit role boundaries instead of undifferentiated text. The transcript is still sent as one SDK user message; this does not introduce native multi-role history replay or shared Claude sessions. Labels preserve message roles, not individual agent names. Existing single-user-message behavior remains unchanged.
• What do you want reviewers to focus on? Whether the transcript framing clearly distinguishes supplied history from the receiving agent's instructions, whether the formatting coverage captures agent-to-agent handoff scenarios, and whether the sequential sample demonstrates the intended behavior.
• Additional context: the documentation for the query field

Related Issue

Fixes #7894

This overlaps with #7895, which also introduces role labels. This PR additionally provides explicit conversation-history framing, broader formatting coverage, a sequential-agent sample, and the Mapping annotation updates.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue, and the overlapping open PR and differences are explained in Related Issue above.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Unescaped message text can spoof role boundaries, and the sample summary is not module-level.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Preserves role context when Claude receives multi-message history and adds a sequential-agent example.

Changes:

• Adds role-labeled transcript formatting while preserving single-user prompts.
• Broadens runtime keyword argument types to Mapping.
• Adds regression tests and an Anthropic sequential workflow sample.

File summaries

File	Description
python/packages/claude/agent_framework_claude/_agent.py	Formats multi-message prompts with role labels and updates annotations.
python/packages/claude/tests/test_claude_agent.py	Covers role-aware prompt formatting.
python/samples/02-agents/providers/anthropic/anthropic_claude_sequential_agents.py	Demonstrates Claude agent handoff.
python/samples/02-agents/providers/anthropic/README.md	Lists the new sample.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (3 commit(s)): ea6f08b2c7d3, ef5fc035173a, 345c5eb86b99
Model: gpt-5.6-sol-fast

Overview

The review found 2 verified inline finding(s).

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (2 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/claude/agent_framework_claude/_agent.py