Python: Add a BackgroundAgentsProvider for python

[westey-m]

Motivation and Context

It should be easy to have a main agent delegate to background agents, without blocking the main agent.

Description

• Add a BackgroundAgentsProvider for python

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_harness
_background_agents.py	246	20	91%	152, 177–178, 203–205, 208–209, 212–213, 351, 396, 399, 424, 433, 437, 494–497
TOTAL	36543	4329	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7267	34 💤	0 ❌	0 🔥	1m 49s ⏱️

[Copilot]

Pull request overview

Adds a Python BackgroundAgentsProvider to the core harness so a “main” agent can start and manage concurrent background sub-agent runs (start, wait, fetch results, continue, clear), along with a dedicated test suite and public exports.

Changes:

• Introduces BackgroundAgentsProvider, BackgroundTaskInfo, and BackgroundTaskStatus in agent_framework/_harness/_background_agents.py.
• Exports the new provider/types (and default source IDs) from agent_framework/__init__.py.
• Adds comprehensive harness-level tests for tool injection and task lifecycle behaviors.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
python/packages/core/agent_framework/_harness/_background_agents.py	New harness provider implementing background task orchestration via injected tools and session state.
python/packages/core/agent_framework/init.py	Exposes the new provider/types and default IDs as part of the public Python surface.
python/packages/core/tests/core/test_harness_background_agents.py	New test suite covering constructor validation, tool injection, and task lifecycle operations.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 91%

✓ Correctness

The implementation is generally well-structured, but contains a correctness bug in _finalize_task: calling asyncio.Task.exception() on a cancelled task raises CancelledError rather than returning it, making the cancellation-handling branch dead code and causing an unhandled exception if a task is ever cancelled.

✓ Security Reliability

The BackgroundAgentsProvider implementation has one concrete reliability bug: _finalize_task calls completed_task.exception() before checking completed_task.cancelled(), but Python's asyncio.Task.exception() raises CancelledError on cancelled tasks (per Python docs), making the cancellation branch unreachable and causing an unhandled exception to propagate. Additionally, self._runtime entries are never cleaned up, causing a memory leak for long-lived applications with many sessions.

✓ Test Coverage

The test suite provides solid coverage of individual tool behaviors (start, wait, get results, continue, clear) including error cases and validation. However, for a feature whose core value proposition is concurrent background task execution, there are notable gaps: no test exercises multiple concurrent tasks with wait_for_first_completion (only a single task is ever awaited), no test covers the LOST task status path, no test verifies session isolation between different sessions sharing the same provider, and the continue_task test doesn't verify the continued task actually produces retrievable results.

✗ Design Approach

I found one design-level issue: the provider keeps child-agent session handles only in provider memory, so background tasks cannot survive the normal AgentSession persistence/restore lifecycle that the rest of the framework is built around.

Flagged Issues

• python/packages/core/agent_framework/_harness/_background_agents.py stores child sessions only in _runtime.background_sessions and never persists a reconstructable handle. When that in-memory runtime is absent, _refresh_task_state() turns running tasks into LOST and background_agents_continue_task() hard-fails. This conflicts with the session contract that only AgentSession.state is persisted across restores, and bypasses the existing recovery path via get_session(service_session_id, ...).

---

Automated review by westey-m's agents

[eavanvalkenburg]

we have the SerializationMixin for just this purpose (and for less dependency on dataclass library changes)