Skip to main content
AG-Kit provides powerful code execution capabilities through two main executors: sandboxed execution for security and local execution for performance. This guide helps you choose the right tool and use it effectively in your agent’s workflows.

​
When to Use Code Execution Tools

Use these tools when your agent needs to run dynamic code snippets or scripts.

​
Quick Start

from agkit.tools import BuiltInCodeExecutor, UnsafeLocalCodeExecutor
import os

# Pick executor based on scenario
executor = (
    BuiltInCodeExecutor(api_key=os.getenv("E2B_API_KEY"))
    if os.getenv("USE_SANDBOX")
    else UnsafeLocalCodeExecutor()
)

# Run a small Python snippet
result = await executor.execute({
    "language": "python",
    "code": "print(3 * 7)"
})

if result.success:
    print(f"Output: {result.data.stdout}")  # '21'

​
Typical Workflows

  • Data Processing: Read a file, execute a Python script to analyze it, and write the results.
  • Code Generation & Testing: Have an LLM generate code, execute it in a sandbox to verify correctness, and report back.
  • DevOps Automation: Run shell scripts to scaffold projects, lint files, or run tests.

​
Choosing the Right Executor

ExecutorUse CaseKey Benefit
BuiltInCodeExecutorUntrusted Code (from LLMs, users)Security & Isolation
UnsafeLocalCodeExecutorTrusted Code (your own scripts)Performance & Speed
  • Prefer BuiltInCodeExecutor (Sandboxed) when security is paramount. It isolates execution, allows package installation, and provides a controlled environment.
  • Use UnsafeLocalCodeExecutor (Local) for trusted scripts in development or controlled CI environments where you need maximum performance and direct access to local files.

​
Core Features & Configuration

Both executors share a common API but have different backends.

​
Configuration

  • Timeout: Set timeoutMs to prevent runaway scripts.
  • Environment Variables: Pass envs to inject secrets or configuration.
  • Streaming Output: Use onStdout and onStderr for real-time feedback from long-running tasks.
from agkit.tools import BuiltInCodeExecutor
import os

# Example: Sandboxed executor with configuration
executor = BuiltInCodeExecutor(
    api_key=os.getenv('E2B_API_KEY'),
    timeout_ms=60000,  # 1 minute timeout
    envs={'CUSTOM_VAR': 'value'},
    on_stdout=lambda data: print('LOG:', data.line),
)

​
Supported Languages

Execute code in multiple languages and get structured results:

​
Workflow Example: Agent Integration

Combine code execution with other tools like the FilesystemToolkit to build powerful agents. 
from agkit.tools import BuiltInCodeExecutor, FilesystemToolkit, LocalFileOperator
import os

# 1. Create instances of the tools
fs_toolkit = FilesystemToolkit(
    name="fs",
    context={
        "working_directory": os.getcwd(),
        "fs_operator": LocalFileOperator()
    }
)

# 2. Provide the tools to your agent
tools=[executor, *fs_toolkit.get_tools()]
# example only，up to your agent framework
agent = Agent(
    # ... other agent config
    tools=[executor, *fs_toolkit.get_tools()],
    instructions="You are a helpful assistant that can write files and execute code."
)

# 3. Run the agent
response = await agent.run({
    "input": 'Write a python script to "Hello from file!", then run it.'
})