AgentRun

AgentRun is a Python library designed to let Python code generated by large language models (LLMs) run safely and quickly. Built on the Docker Python SDK and RestrictedPython, it provides a simple, transparent, and user-friendly API for managing isolated code execution.

Purpose

Giving LLMs code execution capabilities can significantly improve the accuracy of their answers, for example by calculating 12345 * 54321 or analyzing stock trends. However, directly executing untrusted code poses security risks. AgentRun solves this problem, allowing any LLM to gain code execution capabilities through a single line of code while preventing dangerous code.

Main capabilities

• Safe code execution: Checks whether the generated code contains dangerous elements before execution.
• Isolated environment: The code runs in a fully isolated Docker container.
• Configurable resource management: You can set the computing resources the code may consume, with reasonable defaults provided.
• Timeout control: Set a time limit for how long the script can run.
• Dependency management: Full control over the dependencies allowed to be installed.
• Dependency caching: Dependencies can be pre-cached in the Docker container to optimize performance.
• Automatic cleanup: Cleans up any artifacts created by the generated code.
• REST API: Provides a preconfigured Docker setup with support for self-hosting.
• Transparent exception handling: Returns exactly the same output as running Python locally, including exceptions and traceback information, with no obscure Docker messages.

Usage

There are two ways to use it:

1. As a standalone REST API service (recommended): Clone the GitHub repository and start it to get a complete code execution API. Example request:

   curl -X POST http://localhost:8000/v1/run/ -H "Content-Type: application/json" -d '{"code": "print(\'hello, world!\')"}'
   

2. Install via pip and use it with your own Docker setup:

   pip install agentrun
   

   Then initialize AgentRun and connect to a running Docker container.

Suitable scenarios

• Letting LLMs execute code to answer questions such as mathematical calculations and data analysis.
• Building AI applications that need code interpreter functionality.
• Working with any LLM (such as Groq, OpenAI, Anthropic, or wrapped via litellm), as long as the LLM returns a code snippet.

Limitations

• Requires a Docker environment.
• Under the default configuration, dependency installation may become a performance bottleneck; the median execution time is less than 200 milliseconds with no dependencies, and about 400 milliseconds with one average dependency (such as requests).
• Default resource limits: CPU quota 50000 (about 50% of a single core), timeout 20 seconds, memory 100MB, memory+swap 512MB, all customizable.
• The dependency whitelist allows any package installable via pip by default.

Other information

• 97% test coverage, full static typing, and only two dependencies.
• Project address:https://github.com/tjmlabs/AgentRun