Repository navigation
Meta: Evolve Python environment tools for autonomous agent workflows #26077
Description
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.
Activity