Run Python

run_python runs a Python snippet for an agent and returns its output. Code is passed to subprocess.run as an argv list ([sys.executable, "-c", code]), so the source is preserved verbatim — no shell, no re-tokenisation — identically on POSIX and Windows.

from praisonaiagents import Agent
from praisonai.code.tools import run_python

agent = Agent(
    name="Python Runner",
    instructions="Run short Python snippets and report the output.",
    tools=[run_python],
)
agent.start("Print the sum of the first 10 squares")

The user asks the agent to compute something; the agent runs the snippet as an argv list and returns the captured output.

Code is executed via subprocess.run([sys.executable, "-c", code]) — no shell, no re-tokenisation. Multi-line snippets, backslashes, and mixed quotes are preserved exactly as passed, identically on POSIX and Windows. The return shape matches execute_command.

Quick Start

Give an agent the tool

from praisonaiagents import Agent
from praisonai.code.tools import run_python

agent = Agent(
    name="Python Runner",
    instructions="Run Python snippets and report the output.",
    tools=[run_python],
)
agent.start("Compute 2 ** 20 and print it")

Call it directly

from praisonai.code.tools import run_python

result = run_python("print('hello from python')")
print(result["stdout"])   # hello from python
print(result["exit_code"])  # 0

Verify verbatim source is preserved

Snippets with newlines, backslashes, and mixed quotes that used to break under shell quoting now run intact:

from praisonai.code.tools import run_python

result = run_python(r'''
import json
data = {"path": "C:\\Users\\alice", "note": "she said \"hi\""}
print(json.dumps(data))
''')
# → prints the intact JSON without shell mangling on either OS

How It Works

Passing an argv list means the operating system hands your exact code string to Python as a single argument. There is no intermediate shell to expand $VAR, collapse quotes, or re-split on whitespace — so the caller’s source arrives byte-for-byte.

Before / after

Snippet feature	Old shell-string path	argv-list path
Newlines	Re-tokenised, often mangled	Preserved verbatim
Backslashes (`C:\Users\...`)	Escaped/expanded by the shell	Preserved verbatim
Mixed single/double quotes	Broke quoting, could error	Preserved verbatim
POSIX vs Windows	Diverged	Identical behaviour

Return Shape

run_python returns the same dictionary shape as execute_command:

Key	Type	Description
`success`	`bool`	`True` when the exit code is `0`
`exit_code`	`int`	Process exit code
`stdout`	`str`	Captured standard output
`stderr`	`str`	Captured standard error

from praisonai.code.tools import run_python

result = run_python("import sys; sys.stderr.write('warn\\n'); print('ok')")
result["success"]    # True
result["stdout"]     # "ok\n"
result["stderr"]     # "warn\n"

Best Practices

Use raw strings for backslash-heavy code

Wrap Windows paths or regex-heavy snippets in r'''...''' so your own Python source doesn’t consume the backslashes before run_python ever sees them.

Gate it behind approval for untrusted agents

run_python executes arbitrary code. Pair it with Approval so a human confirms each snippet on untrusted routes.

Set a timeout for long snippets

Pass timeout=<seconds> to bound execution; the default is 60 seconds.

Prefer run_python over hand-building a shell command

Building python -c "..." strings yourself re-introduces the quoting bugs this tool fixes. Pass the code to run_python and let the argv list carry it.

Shell Tools

execute_command and process tools for shell-level tasks.

Approval

Require human approval before an agent runs code.

Protected Paths

Block agents from touching sensitive files.

Code Execution with Tools

Let generated code call back into your registered tools.

Protected Paths

Audit Logging

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Before / after

Return Shape

Best Practices

Shell Tools

Approval

Protected Paths

Code Execution with Tools

​Quick Start

​How It Works

​Before / after

​Return Shape

​Best Practices

​Related

Shell Tools

Approval

Protected Paths

Code Execution with Tools

Quick Start

How It Works

Before / after

Return Shape

Best Practices

Related