Workspace instead of the host. The agent’s shell, file reads/writes, and search all run inside Mirage; mount RAM, S3, GDrive, Slack, etc. and the agent uses them through the same camel API.
Install
camel-ai>=0.2.40,<0.3 and markitdown>=0.1.5. Note: mirage-ai[camel] is mutually exclusive with [openai], [openhands], and [pydantic-ai], camel pins pydantic<=2.12.0 while the other agent SDKs require >=2.12.2. Pick one stack per environment.
Usage
Toolkits
MirageTerminalToolkit
Drop-in replacement for camel’s TerminalToolkit. Same 6 functions, all routed through Workspace.execute():
| Method | Mirage translation |
|---|---|
shell_exec(id, cmd, block=True) | await ws.execute(cmd) |
shell_exec(id, cmd, block=False) | await ws.execute(f"{cmd} &"), uses Mirage’s JobTable |
shell_view(id) | jobs (status) or wait %N (final stdout) |
shell_kill_process(id) | kill %N |
shell_write_content_to_file | cat > path with stdin= |
shell_write_to_process | Returns a clear error, Mirage’s shell is non-interactive |
MirageFileToolkit
Subclasses camel’s FileToolkit, inherits all 7 public methods and every format writer (PDF, DOCX, JSON, CSV, HTML, ipynb, plain text). Path resolution and IO are overridden to route through Mirage; format writers operate on a tempfile and the result is pushed via Workspace.execute(f"cat > {path}", stdin=...).
| Method | Behavior |
|---|---|
write_to_file(title, content, filename) | Format writer runs in tempdir → bytes pushed to Mirage path |
read_file(file_paths) | Bytes pulled from Mirage → tempfile → camel’s MarkItDown converter |
edit_file(file_path, old, new) | In-place text replacement via Mirage |
search_files(file_name, path) | find <path> -name <file_name> |
glob_files(pattern, path) | Same as search_files |
grep_files(pattern, path) | grep -rn <pattern> <path> |
Exports
| Symbol | Purpose |
|---|---|
MirageTerminalToolkit | Camel BaseToolkit exposing the 6 shell tools, backed by Workspace.execute. |
MirageFileToolkit | Subclass of camel’s FileToolkit routing path/IO through Mirage. |
Examples
examples/python/agents/camel/sandbox_agent.py,ChatAgentwith both toolkits over a RAM workspace.