Add execution environments abstraction and toolset by dmontagu · Pull Request #4393 · pydantic/pydantic-ai

dmontagu · 2026-02-21T06:59:58Z

Summary

Introduces ExecutionEnvironment ABC and three implementations (LocalEnvironment, DockerEnvironment, MemoryEnvironment) along with ExecutionEnvironmentToolset for exposing coding-agent-style tools (ls, shell, read_file, write_file, replace_str, glob, grep)
This is the foundation for building coding agents and other agents that need shell and filesystem access, split out from the broader code-mode work for independent review and merge
Code execution capabilities (run_python, run_python_with_functions, Monty environment, NDJSON driver protocol) are intentionally excluded and will come in a follow-up PR

Closes #XXXX

Test plan

250 tests in tests/test_environments.py covering all three environment implementations and the toolset
Lint, typecheck, and format verified locally
CI passes
Documentation renders correctly

Checklist

Selected the correct base branch
AI generated code

Introduces ExecutionEnvironment ABC and three implementations (LocalEnvironment, DockerEnvironment, MemoryEnvironment) along with ExecutionEnvironmentToolset for exposing coding-agent-style tools (ls, shell, read_file, write_file, replace_str, glob, grep). This is the foundation for building coding agents and other agents that need shell and filesystem access, split out from the broader code-mode work for independent review and merge.

github-actions · 2026-02-21T07:05:57Z

Docs Preview

commit:	`0d2b2e9`
Preview URL:	https://09f81118-pydantic-ai-previews.pydantic.workers.dev

docs/environments.md

docs/install.md

When multiple agent.run() calls execute concurrently, a shared environment means they all operate on the same filesystem and processes. The new environment_factory parameter creates a fresh, isolated environment per async-with entry using ContextVar-scoped state. Also renames environment → shared_environment to make concurrency semantics explicit (positional arg, so existing callers still work).

Mark huggingface and outlines-vllm-offline extras as conflicting in uv, and exclude outlines-vllm-offline from --all-extras in CI and Makefile.

- Fix _recv_stream EOF check to distinguish zero-size frames from actual EOF - Make MemoryEnvironment.capabilities dynamic: include 'shell' when command_handler is set - Fix LocalEnvironment.grep to use rglob for recursive file search with glob_pattern - Fix glob_match to use regex for all patterns (fnmatch incorrectly matches '/' with '*') - Fix build_glob_cmd: add parentheses for correct find operator precedence, fix ./ prefix for -path - Add double-enter guard in DockerEnvironment._setup to prevent container leak - Add DockerEnvironment.hardened() convenience constructor for security best practices - Rename docker-sandbox optional dependency to docker-environment - Rename 'env' variable to 'environment' in docs to avoid confusion with env vars - Add lifecycle tip about pre-starting the toolset in docs

Tools are now registered unconditionally at init time and filtered in get_tools() based on the current environment's capabilities. This fixes the issue where environment_factory or use_environment() could expose tools unsupported by the runtime environment. Also unifies the Capability type — removes the toolset-level Capability (with edit_file) and EditStrategy types, using the environment-level Capability (with replace_str/apply_patch) everywhere.

- Add `ToolName` literal type for tool-level names exposed to the model (`edit_file` instead of `edit_file:replace_str`/`edit_file:apply_patch`) - `include`/`exclude` now accept `ToolName` values (e.g. `edit_file`) instead of env-level `Capability` values - Rename `_resolve_capabilities` → `_resolve_tool_names`, which maps env capabilities to tool names then applies include/exclude filtering - Rename `replace_str` tool → `edit_file` (the function exposed to models) - Update `Capability` values: `replace_str` → `edit_file:replace_str`, `apply_patch` → `edit_file:apply_patch` in all environments - Update docs and tests

dmontagu

Fixed the glob_pattern filtering for exact file matches in MemoryEnvironment.grep, matching LocalEnvironment behavior.

…rep glob filtering - Rename `Capability` to `EnvCapability` for clarity - Remove unused `instructions()` method from base class - Fix `_resolve_edit_tool` to fall back to auto-detection when env doesn't support the explicit strategy - Fix `MemoryEnvironment.grep` to skip glob filtering for exact file paths, matching `LocalEnvironment` behavior

- Rename `Capability` → `EnvCapability` to free up the name for other use - `_resolve_edit_tool` now falls back to auto-detection when the explicit `edit_strategy` isn't supported by the environment - Remove `instructions` method from base class and DockerEnvironment, along with associated tests - Update all imports and type annotations across environments and tests

adtyavrdhn · 2026-02-26T17:07:31Z

pydantic_ai_slim/pydantic_ai/environments/docker.py

+            network_disabled: Whether to disable network access.
+            read_only: Whether to mount the root filesystem as read-only.
+                Use with `tmpfs` to provide writable scratch space.
+            cap_drop: Linux capabilities to drop (e.g. `['ALL']`).


No idea what this would do

adtyavrdhn · 2026-02-26T17:07:47Z

pydantic_ai_slim/pydantic_ai/environments/docker.py

+            user: User to run as inside the container (e.g. `'nobody'`).
+            tmpfs: tmpfs mounts as `{path: options}`
+                (e.g. `{'/tmp': 'noexec,nosuid,size=64m'}`).
+            init: Whether to use `--init` to run an init process as PID 1.


This either

adtyavrdhn · 2026-02-26T17:11:13Z

pydantic_ai_slim/pydantic_ai/environments/docker.py

+        cpu_limit: float = 1.0,
+        pids_limit: int = 256,
+    ) -> DockerEnvironment:
+        """Create a hardened Docker environment with security best practices.


I would assume/argue this should be the default when a docker environment is being created anyway?

adtyavrdhn · 2026-02-26T17:13:05Z

pydantic_ai_slim/pydantic_ai/environments/docker.py

+            }
+        )
+
+    async def __aenter__(self) -> Self:  # pragma: lax no cover


Why not cover this?

adtyavrdhn · 2026-02-26T17:13:52Z

pydantic_ai_slim/pydantic_ai/environments/docker.py

+        if self._memory_limit:
+            kwargs['mem_limit'] = self._memory_limit
+        if self._cpu_limit:
+            kwargs['nano_cpus'] = int(self._cpu_limit * 1e9)


Okay? Need to check why

adtyavrdhn · 2026-02-26T17:14:39Z

pydantic_ai_slim/pydantic_ai/environments/docker.py

+        # Ensure work_dir exists
+        self._container.exec_run(['mkdir', '-p', self._work_dir])
+
+    async def __aexit__(self, *_args: Any) -> None:  # pragma: lax no cover


Should cover it and what is up with *_args?

adtyavrdhn · 2026-02-26T17:39:18Z

Douwe: It would be kind of nice to have hooks / envs to setup the repo or just actions. This was discussed for David's agent

adtyavrdhn · 2026-02-26T18:10:56Z

pydantic_ai_slim/pydantic_ai/environments/docker.py

+        def _check() -> bool:
+            assert self._container is not None
+            try:
+                self._container.reload()


Why reload it when we only needed to check if it is running?

github-actions bot added size: XL Extra large PR (>1500 weighted lines) feature New feature request, or PR implementing a feature (enhancement) labels Feb 21, 2026

This comment was marked as resolved.

Sign in to view

dmontagu commented Feb 21, 2026

View reviewed changes

docs/environments.md Outdated Show resolved Hide resolved

dmontagu commented Feb 21, 2026

View reviewed changes

docs/environments.md Show resolved Hide resolved

dmontagu commented Feb 21, 2026

View reviewed changes

docs/environments.md Outdated Show resolved Hide resolved

dmontagu commented Feb 21, 2026

View reviewed changes

docs/install.md Outdated Show resolved Hide resolved

dmontagu added 2 commits February 21, 2026 01:37

Remove unused variable in doc example

c847585

This comment was marked as resolved.

Sign in to view

Fix type errors: use lists instead of sets for include/exclude args

00be4ca

This comment was marked as resolved.

Sign in to view

dmontagu added 2 commits February 21, 2026 03:01

Work around huggingface/vllm dependency conflict

33604e6

Mark huggingface and outlines-vllm-offline extras as conflicting in uv, and exclude outlines-vllm-offline from --all-extras in CI and Makefile.

This comment was marked as resolved.

Sign in to view

dmontagu commented Feb 21, 2026

View reviewed changes

dmontagu added 3 commits February 21, 2026 16:10

Merge branch 'main' into execution-environments

9460ea5

dmontagu added the auto-review label Feb 21, 2026

This comment was marked as resolved.

Sign in to view

adtyavrdhn reviewed Feb 26, 2026

View reviewed changes

adtyavrdhn added 2 commits February 27, 2026 11:44

adding for cov

9cf206a

adding for cov

c55a0df

This comment was marked as resolved.

Sign in to view

adtyavrdhn added 2 commits February 27, 2026 12:08

glob removing, need to ensure tests removal for now

2386886

glob removing, need to ensure tests removal for now

802161f

This comment was marked as resolved.

Sign in to view

adtyavrdhn added 2 commits February 27, 2026 13:06

removing ls and grep

ef04316

lint

dbbc126

This comment was marked as resolved.

Sign in to view

adtyavrdhn added 2 commits February 27, 2026 13:23

non blocking writes / reads

29ff88c

addressing issues with open sockets

3623284

This comment was marked as resolved.

Sign in to view

cov

e423283

This comment was marked as resolved.

Sign in to view

adtyavrdhn added 5 commits February 27, 2026 14:11

cov

114ac84

docker fix timeout 0 unintentional

26ba4e8

merge this shit

e52ae45

coverage for timeouts

529b0e0

removing truncation? We don't need it in the execution env

46c57bf

This comment was marked as resolved.

Sign in to view

adtyavrdhn added 2 commits February 27, 2026 15:52

removing truncation tests

bff3271

removing truncation tests

0d2b2e9

Conversation

dmontagu commented Feb 21, 2026

Summary

Test plan

Checklist

Uh oh!

github-actions bot commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docs Preview

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

dmontagu left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

adtyavrdhn Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

adtyavrdhn Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

adtyavrdhn Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

adtyavrdhn Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

adtyavrdhn Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adtyavrdhn Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

adtyavrdhn commented Feb 26, 2026

Uh oh!

adtyavrdhn Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

github-actions bot commented Feb 21, 2026 •

edited

Loading

adtyavrdhn Feb 26, 2026 •

edited

Loading