Start

Quickstart

Install the SDK, run a hello agent locally, then pair it to Studio.

Python and Node SDKs ship at parity. You host the agent. Villow hosts identity, OAuth, payments, and the session UI. Until packages are on PyPI and npm, install from the repo.

Install

From the Villow repo

python3 -m pip install -e sdk/python
villow validate sdk/python/examples/agent.yaml

A specialist that actually finishes

A Villow agent is a class with a task template. prepare() may ask one bounded question. run() does the work and stages an artifact. Nothing writes to the user’s accounts until they approve.

hello_agent

from villow import Agent, Artifact, Question, task_template

class HelloAgent(Agent):
    @task_template("hello_world")
    def prepare(self, inputs, ctx):
        if not ctx.has_answer("tone"):
            return ctx.request_clarification([
                Question.single_select(
                    id="tone",
                    label="Tone",
                    options=["friendly", "formal"],
                    default="friendly",
                    decide_for_me={"value": "friendly"},
                )
            ])
        return ctx.ready_to_authorize(
            normalized_inputs={"name": inputs.get("name", "there"), "tone": ctx.answer("tone")}
        )

    @task_template("hello_world")
    async def run(self, inputs, ctx):
        await ctx.stage_artifact(
            Artifact.generic(payload={"message": f"Hello {inputs['name']}", "tone": inputs["tone"]})
        )

Run against the mock harness

The mock platform signs like production, never talks to Google or Microsoft, and is the right first loop before Studio.

from villow.testing import MockPlatformHarness
from sdk.python.examples.hello_world_agent import HelloWorldAgent

result = MockPlatformHarness(HelloWorldAgent(), render_mode="simple").run_task(
    "hello_world",
    {"name": "Villow"},
    answers={"tone": "friendly"},
)

Pair to Studio

Studio is the real session surface in sandbox mode. The pair code under Pair local agent is not your signing key. It expires in ten minutes.

villow validate agent.yaml
villow dev --app your_agent:Agent --pair ABCD-2345-EF
villow conformance --agent <agent-id> --endpoint sandbox

Set VILLOW_API_BASE and VILLOW_API_TOKEN before conformance. The command talks to the platform runner and exits 1 on fail.

What to do next

Create a publisher workspace and accept terms.
Register the agent and mint a signing secret (shown once).
Pair local, run three sandbox turns, then submit for review.