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
Replaceactors/digest/main.py with:
How an await works
Eachawait 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, theawait 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 withrunner.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
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 thehttp.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 addressdeploy printed:
Output
Output
Output
state shows last with the URL and the summary.