Skip to content

Belgie

Belgie embeds a Deno-powered JavaScript and TypeScript runtime in Python. Use it to execute scripts with explicit permissions, manage JavaScript dependencies, build React MCP Apps, or give AI agents a run_code tool.

Choose a path

If you need to... Start with Why
Execute a JavaScript, TypeScript, or TSX module Runtime Run inline or file-based Script modules from Python.
Share dependencies or a workspace across runs Environment Resolve npm, JSR, URL, and local file dependencies with a lockfile.
Invoke an installed JavaScript package binary Command Run tools such as Vite through the same runtime boundary.
Attach a React widget to an MCP tool MCP Apps Connect Python tools, Vite widgets, and typed tool callers.
Let an agent write JavaScript or TypeScript AI agents Add run_code to Pydantic AI or LangChain.

Install

Start with the core runtime:

uv add belgie

Add an integration extra when you need one. The Install guide lists every extra and the dependencies it adds.

Run a script

The smallest useful Belgie program creates a Script, enters a Runtime, and calls the exported function. Values crossing the Python and JavaScript boundary must be JSON-compatible.

hello.py
import asyncio

from belgie import Runtime, Script

script = Script("""
export default function run(name: string): string {
  return `Hello, ${name}!`;
}
""")


async def main() -> None:
    async with Runtime() as runtime:
        greeting = await runtime(script)("Belgie")
    print(greeting)


asyncio.run(main())

The Runtime and Script guides explain synchronous and asynchronous use, file-based scripts, imports, and the data bridge.

Build an MCP App

Use BelgieExtension to connect a Python MCP tool to a React widget at <name>/widget.tsx. Belgie uses Vite during development and serves self-contained widget HTML in production. Follow the MCP Apps example for the complete workflow.

Give an agent run_code

Install one supported integration:

uv add "belgie[pydantic-ai]"

Then add Belgie to the agent:

from pydantic_ai import Agent

from belgie.pydantic_ai import BelgieCapability

agent = Agent("openai:gpt-5", capabilities=[BelgieCapability()])
result = agent.run_sync("Use TypeScript to convert 'hello-world' to camelCase.")
print(result.output)

See the AI agent overview for the tool contract and safety boundaries, then choose the Pydantic AI or LangChain integration.

Next steps