[Naveen Chatlapalli (1aifanatic)]

Motivation & Context

Several code examples in agent-framework-core docstrings fail when copied. They import names the root package doesn't export, pass removed keyword arguments, or read attributes that don't exist:

file	example	on main
observability.py	from agent_framework import ObservabilitySettings (also get_tracer, get_meter)	ImportError
security.py	from agent_framework import LabelTrackingFunctionMiddleware	ImportError
security.py (get_security_tools)	Agent(chat_client=client, ...)	TypeError: unexpected keyword argument 'chat_client'
security.py (apply_mcp_security_labels)	ChatCompletionAgent(chat_client=..., context_providers=[SecureAgentConfig(chat_client=client)])	no ChatCompletionAgent in Agent Framework; SecureAgentConfig has no chat_client
_middleware.py (ChatContext)	context.chat_client	AttributeError; the attribute is client
_middleware.py (AgentMiddleware)	context.result.is_error	AttributeError; AgentResponse has no is_error
_evaluation.py (module docstring)	results.raise_for_status()	AttributeError; evaluate_agent returns list[EvalResults]

Description & Review Guide

• What are the major changes? Docstring examples only:
  • Import from agent_framework.observability and agent_framework.security.
  • Pass client= to Agent and quarantine_chat_client= to SecureAgentConfig.
  • Use context.client in the ChatContext example.
  • Rewrite RetryMiddleware to retry call_next() when it raises.
  • Call raise_for_status() on each EvalResults, as samples/02-agents/evaluation/evaluate_agent.py does.
• What is the impact of these changes? Documentation only.
• What do you want reviewers to focus on? The RetryMiddleware rewrite. I checked that calling call_next() again after a failed attempt re-runs the chat client: with a client that fails once, the agent returns the second response after one retry.

I found these by extracting the Python examples from the package docstrings and running pyright on them (unknown import symbol, No parameter named, Cannot access attribute). I then ran each corrected form, and the original form where it fails, against the installed packages. The remaining pyright reports in these modules refer to helpers the examples define themselves, such as self.count_tokens. Related core tests pass (872 passed, 14 skipped).

Related Issue

N/A - trivial change: docstring examples are corrected to the current API, with no behavior change.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Claude Code helped extract and type-check the docstring examples, verify the corrected forms at runtime, make the edits, and draft this description.

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 links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• 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.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The retry example must preserve explicit middleware abort and termination signals rather than retrying them.

1 open issue

• Preserve explicit middleware aborts before generic retry handling · New

What changed in this PR

This PR updates Python core docstring examples to match current Agent Framework APIs. It changes documentation only, not runtime implementations.

Changes:

• Correct public imports, constructor keywords, and middleware attribute access.
• Rewrite the retry example to handle raised exceptions.
• Check evaluation status on each returned result.

File	Description
python/​packages/​core/​agent_framework/​security.py	Correct security imports and agent configuration examples.
python/​packages/​core/​agent_framework/​observability.py	Import observability APIs from their public module.
python/​packages/​core/​agent_framework/​_middleware.py	Update client access and exception-based retry examples.
python/​packages/​core/​agent_framework/​_evaluation.py	Call raise_for_status() on individual evaluation results.

_{Review effort: Balanced}

[Naveen Chatlapalli (1aifanatic)]

Good catch — the docs for MiddlewareFailure say middleware must not swallow it. The example now re-raises MiddlewareFailure and MiddlewareTermination before the generic retry handler (both imported from agent_framework). Checked by running the example class directly: a transient RuntimeError is retried once and then succeeds, and either signal propagates after a single call.