yoagent-workers
Run yoagent on Cloudflare Workers through the Worker's own bindings.
Requires yoagent 0.24 or later (the first release with
decision::parse_systemone_response).
yoagent itself builds for wasm32-unknown-unknown (default-features = false)
and reaches every LLM provider over the Worker's fetch (see the
WebAssembly & Cloudflare Workers guide).
This crate adds what only a Worker has: the objects the Workers runtime hands
it in env, already authenticated as your account, so no API token is needed
(and, per Cloudflare, bindings are faster and less restricted than the REST
API). yoagent's core never depends on it.
| Module | Binding | Gives you |
|---|---|---|
ai |
Workers AI (env.AI) |
Cloudflare's Clef decision models as a yoagent DecisionModel |
Workers AI decision models: Clef
# wrangler.toml
[]
= "AI"
# Cargo.toml
[]
= { = "0.24", = false, = ["decision"] }
= "0.1"
Take both from the same source: crates.io for both as above, or git for both.
A crates.io yoagent next to a git yoagent-workers is two yoagent crates
whose types do not match.
// In a workers-rs fetch handler. `worker::Error` has no conversion from
// `DecisionError`, hence the `map_err`.
let clef = clef;
let urgent = clef
.noul
.await
.map_err?;
clef(..) and clef_flash(..) take the binding as workers-rs's Ai or as
the raw env.AI JsValue, and return an ordinary DecisionModel: batched
questions and fallbacks (.or(..)) work, and it can be handed to an agent's
advisory hints, tool gate or input guard like any other decision model
(that use is untested on the binding path). They are priced at the
prices.json rate the price table holds when they are built (cloudflare/clef
$0.24, cloudflare/clef-flash $0.09 per million input tokens by default; a
later price override does not reprice them). That is the list price;
Cloudflare bills in neurons with a daily free allocation.
For another SystemOne model on Workers AI, or your own capabilities, retry policy or price, use the backend directly:
use DecisionModel;
use ;
let model = from_backend;
A binding belongs to one request. Build the decision model, and the agent
that uses it, inside the handler from that request's env.
Errors. What env.AI.run throws or rejects with is read for a leading
Workers AI error code, and classified like the REST API's:
| Binding error | DecisionError |
Retried |
|---|---|---|
3040 out of capacity |
RateLimited (429) |
yes, AiBackend::with_retry (default 3, from 1 s) |
3036 daily free allocation used up |
Http (429) |
no |
| anything else | Backend, with the binding's message |
no |
How the binding words its errors is not documented by Cloudflare, so the code
match is best effort. A value without a run method is Invalid, before
anything is called; a state over Clef's token limits is Invalid before the
binding runs. A .or(..) fallback applies to every failure.
Outside a Worker, or with an API token instead of a binding, use yoagent's own
DecisionModel::clef(account_id), which calls the Workers AI REST API.
Testing
Everything here exists only on wasm32. The tests run under Node against fake
bindings (JavaScript objects whose run records its arguments):
CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner \
Not tested against a real Workers AI binding (that needs wrangler dev and a
Cloudflare account).