[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Invalid optional numeric or boolean values supplied through environment variables and .env files could silently become raw strings or False, hiding configuration mistakes. The agent documentation also used unsupported constructor arguments, and applications need explicit resource-lifecycle methods alongside async with.

Description & Review Guide

• What are the major changes? Validate environment and .env scalar settings with field/source-specific errors while retaining precedence and valid provider settings; add async open()/close() to RawAgent and Agent, delegate async context management to them, and clean up partial startup; correct the default_options examples and add focused regressions.
• What is the impact of these changes? Invalid supplied values now fail immediately; valid settings, callable overrides, SecretString, and existing context-manager behavior remain supported. Explicit lifecycle control is now available.
• What do you want reviewers to focus on? Nullable-union coercion (including provider-specific string arms) and client/MCP cleanup after partial initialization or a lazy connection.

Related Issue

None; this PR intentionally has no linked issue.

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 there is no other open PR for this issue (see 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]

Copilot review overview

🟡 Changes recommended

Nullable Any and non-string Literal settings are incorrectly rejected.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2

Open (2)

• Preserve raw values for Any union members · New
• Coerce environment values for non-string Literal members · New

What changed in this PR

Adds stricter Python settings validation and explicit agent resource lifecycle management.

Changes:

• Validates environment and .env scalar values.
• Adds open() and close() to agents with cleanup handling.
• Updates documentation and regression tests.

File	Description
python/​packages/​core/​agent_framework/​_settings.py	Adds source-aware coercion errors.
python/​packages/​core/​agent_framework/​_agents.py	Adds explicit lifecycle methods and fixes examples.
python/​packages/​core/​tests/​core/​test_settings.py	Tests settings validation and precedence.
python/​packages/​core/​tests/​core/​test_agents.py	Tests lifecycle and partial-startup cleanup.
python/​packages/​core/​AGENTS.md	Documents the new behavior.

---

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