AstraForge Toolkit

Lightweight Python package for using AstraForge DeepAgent and sandboxes from another project.

Contents:

• astraforge_toolkit.SandboxBackend: DeepAgents backend that executes via the remote AstraForge sandbox API.
• astraforge_toolkit.DeepAgentClient: HTTP client for DeepAgent conversations, sandbox sessions (create/list/heartbeat/stop/delete), file upload/download/export, and streaming replies.
• Remote sandbox tools: sandbox_shell, sandbox_python_repl, sandbox_open_url_with_playwright, sandbox_view_image — all execute inside the sandbox via HTTP.

Install

pip install astraforge-toolkit

Quick start

Create a sandbox-backed DeepAgent

from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from astraforge_toolkit import (
    SandboxBackend,
    sandbox_shell,
    sandbox_python_repl,
    sandbox_open_url_with_playwright,
    sandbox_view_image,
)

def backend_factory(rt):
    return SandboxBackend(
        rt,
        base_url="https://your.astra.forge/api",
        api_key="your-api-key",
        # optional: session_params={"image": "astraforge/codex-cli:latest"},
    )

model = ChatOpenAI(model="gpt-4o", api_key="...")
agent = create_deep_agent(model=model, backend=backend_factory)

# Optional: register sandbox tools with your agent/tool registry
tools = [sandbox_shell, sandbox_python_repl, sandbox_open_url_with_playwright, sandbox_view_image]

Create a sandbox session (no DeepAgent conversation)

from astraforge_toolkit import DeepAgentClient

client = DeepAgentClient(base_url="https://your.astra.forge/api", api_key="your-api-key")
sandbox = client.create_sandbox_session(session_params={"image": "astraforge/codex-cli:latest"})

# Upload text (or bytes) into the sandbox workspace
client.upload_file(sandbox.session_id, "/workspace/hello.txt", content="hello from toolkit!\n")

# Download the file back; omit encoding to get raw bytes
print(client.get_file_content(sandbox.session_id, "/workspace/hello.txt", encoding="utf-8"))

# Export a file as an artifact (resolves download URL when configured)
artifact = client.export_file(
    sandbox.session_id,
    "/workspace/hello.txt",
    filename="hello.txt",
    content_type="text/plain",
)
print("artifact id:", artifact.artifact_id, "download:", artifact.download_url)

# Keep the sandbox alive or clean it up when finished
client.heartbeat_sandbox_session(sandbox.session_id)
client.stop_sandbox_session(sandbox.session_id)  # or client.delete_sandbox_session(...)

Call DeepAgent over HTTP

from astraforge_toolkit import DeepAgentClient

client = DeepAgentClient(base_url="https://your.astra.forge/api", api_key="your-api-key")
conv = client.create_conversation()

for chunk in client.stream_message(conv.conversation_id, "Hello, sandbox!"):
    print(chunk)

Build & publish

cd astraforge-python-package
python -m build
python -m twine upload dist/*  # or use --repository testpypi

Configure ~/.pypirc or set TWINE_USERNAME=__token__ and TWINE_PASSWORD=<pypi-token> for uploads.

Examples

See examples/local_api_test.ipynb for a quick notebook that exercises the client against a local http://localhost:8001/api instance.