cave-agent

CaveAgent transforms LLM agents from text-in-text-out systems into stateful runtime operators that work with native Python objects. It provides two runtime backends—IPythonRuntime for same-process execution with zero-copy object access, and IPyKernelRuntime for process-isolated execution with crash resilience. You can inject DataFrames, database connections, models, and custom class instances as first-class variables that persist across turns without serialization. The runtime executes Python code directly, retrieves manipulated objects as native types, and supports both function calling and agent skills. This approach eliminates context window bloat from large state objects and enables complex workflows like data visualization, multi-agent coordination, and real-time streaming.

[{"step":"Initialize CaveAgent in your Python environment. Ensure you have the required dependencies installed (e.g., `pip install cave-agent`).","tip":"Run `import cave_agent; agent = cave_agent.CaveAgent()` to start a new agent session with stateful capabilities."},{"step":"Inject a Python object into the agent's state using `agent.inject_object(OBJECT_NAME, OBJECT_STATE)`. Choose a descriptive name for the object (e.g., `user_session`, `config_manager`).","tip":"Use dictionaries or custom classes for complex state management. Avoid injecting large objects (>10MB) to prevent performance issues."},{"step":"Retrieve the object in subsequent turns with `agent.get_object(OBJECT_NAME)` to inspect or modify its state.","tip":"Always retrieve the object before modifying it to ensure you're working with the latest state. Use deep copies if you need to manipulate the state without affecting the original."},{"step":"Update the object's state using `agent.update_object(OBJECT_NAME, UPDATED_STATE)` after making changes.","tip":"Validate the updated state before calling `update_object` to avoid corrupting the persistent state. Log changes for auditing purposes."},{"step":"Chain operations across multiple agent turns by referencing the same object name. The state will persist until the agent session ends or the object is explicitly removed.","tip":"Use `agent.remove_object(OBJECT_NAME)` to clean up objects when they're no longer needed, especially in long-running workflows."}]