Actions and triggers

Actions are the integrations your agent can call: open a GitHub issue, query Linear, read a Stripe invoice. They come in packs. A pack is a signed, versioned bundle of actions and triggers for one service, named <namespace>/<name> such as io.b3os/github. One action is one operation, called by reference:

text
io.b3os/github/create-issue@1.2.0

Every action is also a valid MCP tool, with its input schema, output schema and an effect class.

Search, describe, call

An agent needs three calls to use an action it has never seen:

1. Search with words: GET /v1/actions/search?q=create a github issue returns references ranked for agents.
2. Describe a reference: GET /v1/actions/describe?ref=io.b3os/github/create-issue@1 returns its input and output schemas, its effect class and the connections it needs. A major version like @1 resolves to the newest matching release.
3. Call it: POST /v1/actions/call validates the input, runs the action, validates the output and returns it.

Calling actions walks through all three. Over MCP the same flow is three tools, actions_search, actions_describe and actions_call, so the whole catalog never crowds the tool list.

Credentials stay out of reach

An action that talks to a service needs your credential for it, stored as a vault connection. You never pass the secret in a call. The action's request leaves through the egress proxy on the node, which adds the credential there, and only for the hosts the pack declares. The action's code, your agent, the model and the logs never see it.

How actions run

Templates and mappings are CEL inside ${{ }}, the same language routines use.

Each action has an effect class: pure (computes from its input), read, write or irreversible. B3OS retries only pure and read actions on its own, and MCP clients see matching hints, such as readOnlyHint for reads.

Triggers

Packs can also provide triggers: webhooks from the service, polls with a cursor, or schedules. A routine subscribes to one with a type: action trigger, and each event starts a run. See pack triggers.

The catalog

The v0.1 catalog holds about 25 curated packs whose credential belongs to you (your own API key, token or OAuth token) or that call public APIs without one: generic HTTP and OpenAPI, GitHub, Slack, Linear, Notion, Jira, Discord, S3, read-only Stripe, Google APIs with your own client, read-only Polymarket market data and others. It leaves out packs that would run on keys B3 pays for, route through residential proxies, or sign wallet transactions. GET /v1/actions/packs lists what the node serves.

Every pack version carries a content hash and an Ed25519 publisher signature, and the node verifies both against the registry before loading it. In the beta only B3OS publishes packs. See packs.

Billing and scopes

Each call bills one actions.call, 300 calls a minute per organization in the beta.

Naming a connection in a call also needs vault:run.