Configuring CodeExecutorAgent for Secure Code Execution in AutoGen

To configure secure code execution in AutoGen, use the CodeExecutorAgent with a Docker-based executor and a custom approval_func to vet every code snippet before execution.

The CodeExecutorAgent in the microsoft/autogen repository enables large language models to generate and run code within isolated environments. Configuring this agent for secure code execution requires understanding its dual-layer architecture and implementing proper sandboxing and approval mechanisms.

Architecture of the CodeExecutorAgent

The agent operates through two distinct layers that separate orchestration from execution.

Agent Layer

Located in autogen_agentchat/agents/_code_executor_agent.py, the agent layer handles conversation orchestration, extracts markdown code blocks, and manages the execution-reflection loop. It processes incoming TextMessage objects and coordinates with the underlying code executor.

Code Executor Layer

The execution layer provides the actual sandbox environment. AutoGen offers two implementations:

• Docker executor: autogen_ext/code_executors/docker/_docker_code_executor.py provides OS-level isolation through containers.
• Local executor: autogen_ext.code_executors.local.LocalCommandLineCodeExecutor runs code in local subprocesses and is suitable only for debugging trusted code.

Secure Execution Workflow

The CodeExecutorAgent follows a six-step pipeline to ensure safe code execution.

1. Message Intake and Code Extraction

The agent receives a TextMessage containing markdown code blocks. The _extract_markdown_code_blocks method parses content using a regex built from self._supported_languages_regex to identify executable snippets.

2. Approval Gate

Before execution, the agent checks for an approval_func callback. This function receives an ApprovalRequest containing the extracted code and returns an ApprovalResponse with an approved boolean and reason string. Without this function, the agent raises a runtime warning to remind developers to implement security vetting.

3. Sandboxed Execution

Approved code passes to the CodeExecutor. The DockerCommandLineCodeExecutor writes each block to a file in a working directory and executes it inside a Docker container with auto_remove=True. The executor enforces timeouts, isolates filesystems via volume mounts, and supports GPU device requests.

4. Result Normalization

The executor returns a CodeResult object. The agent normalizes empty outputs and non-zero exit codes into explanatory messages.

5. Event Emission

The agent yields a CodeExecutionEvent and adds the result to the model context for conversation continuity.

6. Reflection Loop

If a model_client is configured, the agent feeds execution outcomes back to the LLM to generate reflective responses, completing the iteration cycle.

Security-Focused Configuration Options

Configure these parameters in CodeExecutorAgent and DockerCommandLineCodeExecutor to harden your deployment:

• approval_func: Implement SyncApprovalFunc or AsyncApprovalFunc to programmatically or manually vet code before execution.
• Docker executor: Use DockerCommandLineCodeExecutor instead of local execution to ensure OS-level isolation with auto_remove=True and filesystem isolation.
• work_dir and bind_dir: Restrict which host paths are visible inside the container. Defaults to tempfile.TemporaryDirectory for isolation.
• extra_volumes and extra_hosts: Explicitly whitelist additional mounts or hostname mappings rather than exposing the entire filesystem.
• timeout: Limit execution time to prevent runaway processes (default 60 seconds).
• delete_tmp_files: Remove temporary source files after execution when set to True.
• stop_container: Guarantee container cleanup when the executor closes or the process exits.

Implementing a Secure CodeExecutorAgent

This complete example demonstrates a secure configuration using Docker isolation and a custom approval function:

import asyncio
from autogen_agentchat.agents import CodeExecutorAgent, ApprovalRequest, ApprovalResponse
from autogen_agentchat.messages import TextMessage
from autogen_ext.code_executors.docker import DockerCommandLineCodeExecutor
from autogen_core import CancellationToken

def safe_approval(request: ApprovalRequest) -> ApprovalResponse:
    """Simple whitelist: only allow pure Python print statements."""
    if "print(" in request.code and "import " not in request.code:
        return ApprovalResponse(approved=True, reason="Allowed safe print")
    return ApprovalResponse(approved=False, reason="Disallowed operation")

async def main() -> None:
    # Initialize Docker-based executor for isolated sandboxing

    executor = DockerCommandLineCodeExecutor(work_dir="coding")
    await executor.start()

    # Create agent with security approval gate

    agent = CodeExecutorAgent(
        name="secure_executor",
        code_executor=executor,
        approval_func=safe_approval,  # Security gate

    )

    # Task containing a code block

    task = TextMessage(
        content='''
Here is a snippet to run:

```python
print("Hello, secure world!")

''', source="user", )

# Execute with cancellation support

response = await agent.on_messages([task], CancellationToken())
print("Agent reply:", response.chat_message.content)

# Cleanup

await executor.stop()

asyncio.run(main())

This pattern aligns with the test suite in [`tests/test_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/tests/test_code_executor_agent.py) and the implementation in [`_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/_code_executor_agent.py).

## Key Source Files

Understanding these files helps you customize and audit the secure execution pipeline:

- **[`autogen_agentchat/agents/_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/agents/_code_executor_agent.py)**: Core agent implementation, approval handling, and execution loop. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_code_executor_agent.py)

- **[`autogen_ext/code_executors/docker/_docker_code_executor.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/code_executors/docker/_docker_code_executor.py)**: Docker-based sandbox configuration, volume mounting, and container lifecycle management. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py)

- **[`autogen_ext/code_executors/local/_local_code_executor.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/code_executors/local/_local_code_executor.py)**: Local subprocess executor for trusted debugging environments. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/code_executors/local/_local_code_executor.py)

- **[`tests/test_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/tests/test_code_executor_agent.py)**: Test suite demonstrating approval functions and Docker integration patterns. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/tests/test_code_executor_agent.py)

## Summary

- The `CodeExecutorAgent` in microsoft/autogen separates orchestration from execution to enable safe LLM-generated code running.
- **Docker isolation** via `DockerCommandLineCodeExecutor` provides the recommended security baseline with `auto_remove=True` and filesystem isolation.
- Implement an **`approval_func`** callback to programmatically vet code before execution, preventing unauthorized operations.
- Configure **`work_dir`**, **`timeout`**, and **`extra_volumes`** explicitly to minimize attack surface and prevent resource exhaustion.
- Reference the source files in [`autogen_agentchat/agents/_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/agents/_code_executor_agent.py) and [`autogen_ext/code_executors/docker/_docker_code_executor.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/code_executors/docker/_docker_code_executor.py) to customize the secure execution pipeline.

## Frequently Asked Questions

### What is the difference between CodeExecutorAgent and a regular AssistantAgent?

The `CodeExecutorAgent` is specifically designed to extract markdown code blocks from messages and execute them in a sandboxed environment, whereas a standard `AssistantAgent` focuses on conversational responses without built-in code execution capabilities. The `CodeExecutorAgent` implements a dedicated execution-reflection loop with approval gates that standard agents lack.

### Why should I use DockerCommandLineCodeExecutor instead of the local executor?

You should use `DockerCommandLineCodeExecutor` because it provides OS-level isolation through containerization, automatically removes containers after execution with `auto_remove=True`, and restricts filesystem access via volume mounts. The local executor (`LocalCommandLineCodeExecutor`) runs code directly on your host machine and should only be used for debugging trusted code, as it offers no protection against malicious operations.

### How do I implement a custom approval function for CodeExecutorAgent?

Implement a callable that accepts an `ApprovalRequest` object and returns an `ApprovalResponse` with `approved` (boolean) and `reason` (string) fields. You can define either a synchronous function (`SyncApprovalFunc`) or asynchronous coroutine (`AsyncApprovalFunc`). In your implementation, inspect the `request.code` string to enforce security policies—such as whitelisting specific functions or blocking imports—before returning the approval decision.

### What security settings should I configure to prevent resource exhaustion?

Configure the **`timeout`** parameter (default 60 seconds) to limit execution time and prevent runaway processes. Set **`delete_tmp_files=True`** to ensure temporary source files are removed after execution. When using the Docker executor, explicitly define **`work_dir`** and avoid overly permissive **`extra_volumes`** to minimize filesystem exposure. Additionally, ensure **`stop_container`** is enabled to guarantee container cleanup when the executor closes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}