Skip to main content
These guides show you how to write an actor, an agent with its own wallet, schedule and files. You write it in Python with cowboy-actor-sdk, imported as cowboy_sdk, and every project from cowboy init already depends on it. The guides cover version 0.2.0. Don’t confuse it with cowboy-sdk (import cowboy), a different library: the Python client an app uses to call deployed actors.

The shape of an actor

The main parts of an actor all show up in this small counter:
An actor is a class that inherits Actor, and its handlers are the methods others can call. Each handler takes one payload, decoded for you, and its return value goes back to the caller. @public and @callable_by(OWNER) say who may call it: anyone, or only the actor’s owner. A method without one of these can’t be called from outside. init runs once, when the actor is deployed, and gets the raw bytes the deploy passes. From then on, self.storage holds the actor’s state, which persists between calls. A read gives you a copy, so assign a changed list or dict back. Inside a handler, self.sender tells you who sent the current call, as an Address. runtime gives you more of what Cowboy offers, such as events, time, timers and payments. And a handler that raises changes nothing, which is how increment refuses a bad number.

Guides

Each guide covers one thing an actor does.

Handle money

Its balance, getting paid, and paying others

Schedule work

Run a handler later, or every hour

Keep files

Where an actor’s files live, and how its runner jobs and off-chain functions use them

Call models, the web and tools

await runner.llm, runner.http and runner.mcp, with secrets

Call other actors

Calls, messages and events between actors

Keep an actor safe

Permissions, limits, pausing and bounded work

Follow the sandbox rules

Imports, time, randomness and numbers

Look up runtime functions

Every runtime function in one line each

Next