Goal
Once the Python Environments extension is the default environment implementation, an agent should be able to create and configure exactly the Python environment it needs through a clear, reliable tool contract.
The long-term rich environment tooling should be owned by Python Environments. Until then, the Python extension should provide a lowest-common-denominator compatibility tool that works whether Python Environments is enabled or disabled.
Why this needs coordinated work
Today, configure_python_environment is an orchestrator rather than a declarative creation tool:
- Its public input is effectively limited to
resourcePath.
- The agent cannot request an environment type, Python constraint, location, dependencies, or replacement behavior.
- Tool auto-approval does not suppress Quick Picks, so an approved call can still block waiting for the user.
- The Python and Python Environments backends do not support the same inputs.
- Tool schemas are statically contributed, so one tool cannot safely advertise a richer schema only when Python Environments happens to be active.
This means adding backend-specific arguments to the current tool could produce requests that are accepted by the schema but cannot be honored by the active backend.
Design principles
- A non-interactive invocation must either complete autonomously or return an actionable error; it must never wait on UI.
- Requested environment properties are enforceable outcomes, not best-effort hints. Unsupported requests fail explicitly.
- Capability decisions are based on the active backend, not whether an extension is merely installed.
- Distinct capabilities should have stable tool identities and contracts rather than a schema that appears to change dynamically.
- Users who disable Python Environments retain a smaller compatibility surface instead of seeing options that may silently fail.
- Tool shape and descriptions should be validated against representative agent tasks before the final API is fixed.
Workstreams
1. Fix the current high-priority blocking bug
Make the existing compatibility tool safe for auto-approved/autopilot use. See #25940.
PR #26072 removes a redundant tool-preparation confirmation, but it does not remove the environment Quick Pick that can still block an approved call.
2. Investigate the best model-facing tool surface
Compare the current high-level orchestrator with surfacing granular environment operations and with a richer declarative tool. Measure whether changing the available tools and descriptions improves task outcomes before committing to the long-term contract.
3. Move rich environment tooling to Python Environments
After Python Environments is the default and the investigation has produced a recommendation, it should contribute the richer tool contract. That contract may include:
- environment type;
- Python version/interpreter constraints;
- environment name and location;
- dependencies;
- reuse/replacement behavior;
- selection behavior;
- interaction policy;
- capability discovery;
- structured success and failure results.
The Python extension can retain or deprecate the compatibility tool based on migration and disabled-extension requirements.
Proposed sequence
- Fix the no-interaction/autopilot behavior in the current tool.
- Run controlled agent evaluations across alternative tool surfaces.
- Use the results to define the Python Environments-owned declarative contract.
- Plan tool identity, rollout, compatibility, and deprecation before changing ownership.
Success criteria
- Auto-approved environment setup never blocks on extension UI.
- Agents can request the environment properties required by a task and receive either that exact outcome or a structured unsupported/conflict error.
- Creation, dependency installation, selection, and verification are represented accurately in tool results.
- The Python-extension fallback remains honest and usable when Python Environments is disabled.
- The final tool set is supported by comparative agent-outcome data.
Related
Goal
Once the Python Environments extension is the default environment implementation, an agent should be able to create and configure exactly the Python environment it needs through a clear, reliable tool contract.
The long-term rich environment tooling should be owned by Python Environments. Until then, the Python extension should provide a lowest-common-denominator compatibility tool that works whether Python Environments is enabled or disabled.
Why this needs coordinated work
Today,
configure_python_environmentis an orchestrator rather than a declarative creation tool:resourcePath.This means adding backend-specific arguments to the current tool could produce requests that are accepted by the schema but cannot be honored by the active backend.
Design principles
Workstreams
1. Fix the current high-priority blocking bug
Make the existing compatibility tool safe for auto-approved/autopilot use. See #25940.
PR #26072 removes a redundant tool-preparation confirmation, but it does not remove the environment Quick Pick that can still block an approved call.
2. Investigate the best model-facing tool surface
Compare the current high-level orchestrator with surfacing granular environment operations and with a richer declarative tool. Measure whether changing the available tools and descriptions improves task outcomes before committing to the long-term contract.
3. Move rich environment tooling to Python Environments
After Python Environments is the default and the investigation has produced a recommendation, it should contribute the richer tool contract. That contract may include:
The Python extension can retain or deprecate the compatibility tool based on migration and disabled-extension requirements.
Proposed sequence
Success criteria
Related