TaskWeaver

Converts natural language user requests into executable Python code plans by routing through a Planner role that decomposes tasks into sub-steps, then coordinates CodeInterpreter and External Roles to generate and execute code. The Planner maintains a YAML-based prompt configuration that guides task decomposition logic, ensuring structured workflow orchestration rather than free-form text generation. Unlike traditional chat-based agents, TaskWeaver preserves both chat history AND code execution history (including in-memory DataFrames and variables) across stateful sessions.

The CodeInterpreter role generates Python code based on Planner instructions, then executes it in an isolated sandbox environment with access to a plugin registry. Code generation is guided by available plugins (exposed as callable functions with YAML-defined signatures), and execution results (including variable state and DataFrames) are captured and returned to the Planner. The framework uses a Code Execution Service that manages Python runtime isolation, preventing code injection and enabling safe multi-tenant execution.

Supports External Roles (e.g., WebExplorer, ImageReader) that extend TaskWeaver with specialized capabilities beyond code execution. External Roles are implemented as separate modules that communicate with the Planner through the standard message-passing interface, enabling them to be developed and deployed independently. The framework provides a role interface that External Roles must implement, ensuring compatibility with the orchestration system. External Roles can wrap external APIs (web search, image processing services) or custom algorithms, exposing them as callable functions to the CodeInterpreter.

Enables agent behavior customization through YAML configuration files rather than code changes. Configuration files define LLM provider settings, role prompts, plugin registry, execution parameters (timeouts, memory limits), and UI settings. The framework loads configuration at startup and applies it to all components, enabling users to customize agent behavior without modifying Python code. Configuration validation ensures that invalid settings are caught early, preventing runtime errors. Supports environment variable substitution in configuration files for sensitive data (API keys).

Provides evaluation and testing capabilities for assessing agent performance on data analytics tasks. The framework includes benchmarks for common analytics workflows and metrics for evaluating task completion, code quality, and execution efficiency. Evaluation can be run against different LLM providers and configurations to compare performance. The testing framework enables developers to write test cases that verify agent behavior on specific tasks, ensuring regressions are caught before deployment. Evaluation results are logged and can be compared across runs to track improvements.

Maintains session state across multiple user interactions by preserving both chat history and code execution history, including in-memory Python objects (DataFrames, variables, function definitions). The Session component manages conversation context, tracks execution artifacts, and enables rollback or reference to previous states. Unlike stateless chat interfaces, TaskWeaver's session model treats the Python runtime as a first-class citizen, allowing subsequent tasks to reference variables or DataFrames created in earlier steps.

Extends TaskWeaver functionality through a plugin architecture where custom algorithms and tools are wrapped as callable Python functions with YAML-based schema definitions. Plugins define input/output types, parameter constraints, and documentation that the CodeInterpreter uses to generate type-safe function calls. The plugin registry is loaded at startup and exposed to the LLM, enabling code generation that respects function signatures and prevents runtime type errors. Plugins can be domain-specific (e.g., WebExplorer, ImageReader) or custom user-defined functions.

Implements a role-based multi-agent architecture where different agents (Planner, CodeInterpreter, External Roles like WebExplorer, ImageReader) specialize in specific tasks and communicate exclusively through the Planner. The Planner acts as a central hub, routing messages between roles and ensuring coordinated execution. Each role has a specific prompt configuration (defined in YAML) that guides its behavior, and roles communicate through a message-passing system rather than direct function calls. This design enables loose coupling and allows roles to be swapped or extended without modifying the core framework.

Abstracts LLM interactions behind a provider-agnostic interface that supports OpenAI, Anthropic, local LLMs (Ollama, vLLM), and other providers through a unified API. The framework handles provider-specific details (API authentication, request formatting, response parsing) internally, allowing users to swap LLM providers by changing configuration without modifying agent logic. Supports both chat-based and completion-based LLM APIs, with automatic fallback and retry logic for API failures.

Implements a message attachment system that enables passing rich Python data structures (DataFrames, numpy arrays, custom objects) between roles without serialization to JSON or text. Attachments are stored in-memory and referenced by ID in messages, preserving data fidelity and enabling efficient multi-step workflows. The attachment system is defined in taskweaver/memory/attachment.py and handles serialization only when necessary (e.g., for logging or external storage). This approach avoids the performance penalty of converting DataFrames to CSV strings and back.

Provides multiple user interfaces for interacting with TaskWeaver agents: a console-based CLI interface (taskweaver/chat/console/chat.py) for terminal-based interaction and a web UI for browser-based access. Both interfaces expose the same underlying agent capabilities through different presentation layers. The console interface supports streaming output and real-time execution feedback, while the web UI provides a chat-like interface with visualization of execution results. Both interfaces manage session state and handle user input/output formatting.

Executes generated Python code in an isolated sandbox environment (subprocess or containerized runtime) to prevent code injection, infinite loops, and resource exhaustion. The Code Execution Service manages sandbox lifecycle, enforces resource limits (CPU, memory, execution timeout), and captures execution output (stdout, stderr, exceptions). Sandboxing is transparent to the user; generated code runs as if in a normal Python environment but with safety guardrails. The framework supports both subprocess-based isolation (for local execution) and container-based isolation (for distributed deployment).

Provides comprehensive observability into agent execution through detailed logging, tracing, and event emission. The framework logs all major events (task decomposition, code generation, execution, role communication) with timestamps and context. An event emitter system (taskweaver/module/event_emitter.py) enables subscribers to hook into execution events for monitoring, debugging, or custom analytics. Execution traces include role-specific logs, code generation prompts, and execution results, enabling post-mortem analysis of agent behavior. Traces can be exported to external observability platforms or stored locally for audit purposes.