CodeAct Agent

Generates executable Python code as the primary action mechanism for agents instead of JSON tool calls or text responses. The LLM (Mistral-7b or Llama-2-7b) directly outputs Python code that consolidates multiple tool invocations into a single, semantically rich action. This unified approach leverages the full expressiveness of Python syntax, enabling complex logic, error handling, and multi-step operations within a single code block that can be iteratively refined based on execution results.

Executes LLM-generated Python code in containerized, isolated environments (Docker containers or Kubernetes pods) with per-conversation isolation. Each conversation session gets its own sandboxed execution environment managed by a Jupyter kernel, preventing code from one session from affecting others and ensuring security boundaries. The execution engine captures stdout, stderr, and return values, returning execution results back to the LLM for multi-turn refinement.

Consolidates what would typically require multiple tool calls (e.g., 'read file', 'parse JSON', 'filter data', 'write results') into a single Python code block that expresses the complete intent. The LLM generates code that combines these operations semantically, reducing the number of round-trips and enabling more complex logic within a single action. This is enabled by Python's expressiveness compared to rigid tool schemas.

Isolates code execution in containerized environments (Docker containers or Kubernetes pods) with restricted capabilities, preventing code from accessing the host system, other users' data, or system resources. Each conversation runs in its own container with its own filesystem, network namespace, and resource limits. The system can optionally disable dangerous operations (file system access, network calls) through execution policies.

Implements a feedback loop where code execution results (including errors, output, and return values) are fed back to the LLM in subsequent turns, allowing the agent to iteratively refine and correct generated code. The system maintains conversation history with execution results, enabling the LLM to reason about what went wrong and generate corrected code. This creates a dynamic interaction pattern where the agent can debug its own code generation through multiple attempts.

Provides two distinct user interfaces for interacting with the CodeAct agent: a web-based Chat UI with conversation history persistence in MongoDB, and a Python Script interface for programmatic access. Both interfaces communicate with the same underlying LLM service and code execution engine, allowing users to choose interaction patterns based on their workflow. The Chat UI stores full conversation history with execution results, while the Python Script interface enables integration into automation pipelines.

Supports deployment across multiple infrastructure patterns: local laptop (llama.cpp + Docker), production servers (vLLM + Docker), Kubernetes clusters (vLLM + K8s pods), and HPC/Slurm systems. Each deployment variant configures LLM serving, code execution, and user interface components independently, allowing teams to scale from development to production without architectural changes. The modular design decouples these three components so they can be deployed and scaled separately.

Supports multiple LLM model variants (CodeActAgent-Mistral-7b-v0.1 with 32k context window and CodeActAgent-Llama-7b with 4k context window) that can be swapped based on deployment constraints and task complexity. The system is optimized for code generation tasks and allows selection based on available compute resources and conversation length requirements. Model selection directly impacts context window capacity for multi-turn refinement conversations.

Stores full conversation history including user queries, generated code, execution results, and error traces in MongoDB, enabling conversation resumption, audit trails, and analytics. The Chat UI interface integrates with MongoDB to persist state across sessions, while the Python Script interface can optionally integrate with the same storage. This enables teams to track agent behavior, debug failures, and analyze patterns across conversations.

Captures stdout, stderr, return values, and exception traces from executed Python code and returns them to the LLM in a structured format. The execution engine distinguishes between successful execution, runtime errors, and syntax errors, providing detailed error context that enables the LLM to understand what went wrong and generate corrected code. This includes execution duration and resource usage metrics for performance analysis.

Maintains persistent Python environment state (variables, imports, function definitions) across multiple code executions within a single conversation using Jupyter kernel sessions. Each conversation gets a dedicated kernel that preserves state between code blocks, allowing agents to build up complex state incrementally and reference previously defined variables and functions. This enables stateful multi-step workflows where later code depends on earlier computations.

Allows configuration of execution timeouts (max seconds per code block), memory limits (max RAM per kernel), and CPU limits (if running in containers) to prevent runaway code from consuming unbounded resources. These limits are enforced at the execution engine level, terminating code that exceeds thresholds and returning timeout/resource exceeded errors to the LLM. This is critical for preventing denial-of-service scenarios in multi-user deployments.