Python quick start

Scaffold

act-build init python my-component
cd my-component
just init

act-build init carries the templates inside the binary — no copier or uvx needed to start. Pass --http / --fs to have it declare those capabilities in act.toml for you.

The template sets up pyproject.toml with a current act-sdk, a wit/ directory tracking act:tools over act:core, componentize-py as a dev dependency, and a justfile with build / test / publish.

Write a tool

app.py:

from act_sdk import component, tool, ActError


@component
class MyComponent:
    @tool(description="Reverse a string", read_only=True)
    async def reverse(self, text: str) -> str:
        return text[::-1]

    @tool(description="Divide two numbers")
    async def divide(self, a: float, b: float) -> float:
        if b == 0:
            raise ActError("std:invalid-args", "Cannot divide by zero")
        return a / b

Type hints and the method signature become the tool’s JSON Schema automatically. The @component decorator emits the WIT tool-provider export binding expected by componentize-py.

Build

just build

This runs:

uv run componentize-py -d wit -w component-world componentize app -o <name>.wasm
act-build pack <name>.wasm

Python code is baked into a SpiderMonkey-free Python runtime via componentize-py.

Verify

act info <name>.wasm --tools

Run

just test
act call <name>.wasm reverse --args '{"text":"hello"}'

What `act_sdk` gives you

Decorator / type	Purpose
`@component`	Marks a class as the ACT component, generates the WIT bridge
`@tool(description=..., read_only=..., idempotent=..., destructive=..., timeout_ms=...)`	Marks a method as a tool; JSON Schema derived from type hints
`ActError("std:kind", "msg")`	Raise for structured tool errors
`Json[T]` / `Content`	Opt into JSON or explicit MIME type (default is CBOR)

Return types:

str → text/plain
bytes → application/octet-stream
Json(x) → application/json
Content(mime, data) → whatever you say
anything else → CBOR

Known limitations

componentize-py currently requires Python 3.14 runtime to build.
Cold-start is slower than Rust components (Python interpreter bundled).