Execution environment

freeact uses ipybox as sandboxed code execution environment, a solution based on IPython and Docker. There are several options for providing dependencies needed by code actions in ipybox:

• Use a prebuilt Docker image.
• Build a custom Docker image.
• Install dependencies at runtime

Prebuilt Docker images

freeact provides prebuilt Docker images in variants minimal, basic, and example. They have the following dependencies pre-installed:

• ghcr.io/gradion-ai/ipybox:minimal:

  docker/dependencies-minimal.txt

  freeact-skills = {version = "0.0.8", extras = ["search-google", "search-perplexity"]}
  

• ghcr.io/gradion-ai/ipybox:basic:

  docker/dependencies-basic.txt

  freeact-skills = {version = "0.0.8", extras = ["search-google", "search-perplexity"]}
  matplotlib = "^3.10"
  numpy = "^2.2"
  pandas = "^2.2"
  sympy = "^1.13"
  

• ghcr.io/gradion-ai/ipybox:example:

  docker/dependencies-example.txt

  freeact-skills = {version = "0.0.8", extras = ["all"]}
  scikit-learn = "^1.6"
  matplotlib = "^3.10"
  numpy = "^2.2"
  pandas = "^2.2"
  pygithub = "^2.5"
  sympy = "^1.13"
  

Note

The freeact-skills package provides predefined example skills for the freeact agent library.

Note

Prebuilt ipybox images run with root privileges. For non-root execution, build a custom Docker image (see also ipybox's installation guide).

Custom Docker image

To build a custom ipybox image, create a dependencies.txt file with your custom dependencies. For example:

dependencies.txt

freeact-skills = {version = "0.0.8", extras = ["search-google"]}
numpy = "^2.2"
# ...

Note

dependencies.txt must follow the Poetry dependency specification format.

Then build a custom Docker image with ipybox's build command:

python -m ipybox build -t ghcr.io/gradion-ai/ipybox:custom -d dependencies.txt

To use the image, reference it in CodeExecutionContainer with tag="ghcr.io/gradion-ai/ipybox:custom" or in execution_environment with ipybox_tag="ghcr.io/gradion-ai/ipybox:custom":

from freeact import execution_environment

async with execution_environment(ipybox_tag="ghcr.io/gradion-ai/ipybox:custom") as env:
    ...

Installing dependencies at runtime

Dependencies can also be installed at runtime with !pip install <package> using a code executor. When agents require additional Python packages for executing their code actions, they usually install them on demand, either based on prior knowledge or by reacting on code execution errors when an import failed. Alternatively, application code may also install packages at runtime prior to running an agent:

from freeact import execution_environment

async with execution_environment(ipybox_tag="ghcr.io/gradion-ai/ipybox:basic") as env:
    async with env.code_executor() as executor:
        # Install the serpapi package prior to running an agent
        await executor.execute("!pip install serpapi")

    async with env.code_provider() as provider:
        # Load skill modules that depend on serpapi
        skill_sources = await provider.get_sources(
            module_names=["my_skill_module_1", "my_skill_module_2"],
        )

    async with env.code_executor() as executor:
        # Initialize and run agent
        # ...

Tip

For production use, it's recommended to include frequently used dependencies in a custom Docker image.