Skip to main content
This page shows how a handler can ask a model, call a web API or use a tool. Actor code can’t reach those itself, so it hands each call to a runner, a machine that does work for actors, and awaits the answer. You’ll build an actor that fetches a page, asks a model to summarize it, and posts the summary to a Telegram chat with a bot token kept secret. First, install the CLI. The last steps deploy, so they need a funded wallet, a Telegram bot token and a chat id.

1. Create the project

Output

2. Write the actor

Replace actors/digest/main.py with:

How an await works

Each await runner.… sends one job to a runner, and the handler stops there. When the answer comes back, the handler continues from the same line, with its local variables as they were. The caller gets its reply at the first await, so read the result later, here with last. Each runner call does one thing: A model’s .text is its reply. A web response’s .data is the parsed JSON, and any other response is base64 under .data["raw"], which is what body_text handles above.

Limits and costs

A wait can’t last forever. @runner.continuation(timeout=2 * HOUR) sets how long it can last, in seconds, and past that the await raises JobFailed. A handler can have at most 8 awaits, one after another. An await can sit in an if or a try, but not in a loop. Once a job fails, nothing asks again, so to try again, await again. The actor pays for each job from its balance. To stop one caller draining it, use @limit (Keep an actor safe).

Failures

If no runner delivers an answer, the await raises JobFailed, and its reason says why. Inside try: ... except JobFailed:, your code handles it, as summarize does twice. Anywhere else, the handler ends at that await, keeps what it stored before it, and the actor sends a cowboy.wait.failed event. Some errors don’t count as failed jobs, because they arrive as the answer and the await doesn’t raise. A model provider’s error comes back with .data as an object with an error key instead of text, which is why summarize checks for it. A web error such as a 404 or 429 arrives as the answer too. Redirects aren’t followed.

Secrets

A job often needs an API key or token, but you should never put one in the actor’s code, its state or a call, because all three are public. Keep it in Cowboy’s secret store instead, and mark where a job uses it with runner.secret(name, prefix=..., suffix=...). The job carries only prefix + suffix, and the runner fills in the value when it makes the request. runner.secret works in a URL, header, request body or tool argument. A secret is released only to the actors it was added for (Your keys and your data).

3. Test it

Tests answer jobs themselves, so they need no model and no network. chain.jobs() lists the jobs a handler started, chain.reply(result) answers the last one, and chain.fail(reason) fails it. Replace tests/test_digest.py with:
Output

4. Run it on your machine

cowboy run answers runner jobs from the command line, and --stub-job-failure <reason> fails the next job:
Output
The CBOR reading is the handler’s answer. Testing toolkit lists every stub.

5. Deploy it with web access

So far, stubs have answered every job. On a network, web requests and tool calls need the http.fetch permission, which you request at deploy in a manifest. Its allowlist_domains lists the hosts the actor may reach. Without it, jobs are refused, and cowboy check won’t warn you. Model calls need no permission. This actor fetches any URL you give it, so it lists *. When you know the hosts, name them instead, as in ["api.example.com", "*.example.org"]. You can’t change the list after the deploy. Save this as manifest.json in the project:
Output

6. Summarize a page

Add the bot token in your browser, since the command never takes the value. Use the address deploy printed:
Output
Then set the chat, using your chat’s id, and ask for a summary:
Output
Output
Each job takes a moment. When they finish, the summary arrives in your Telegram chat, and state shows last with the URL and the summary.

Next