Reference

An action is a named operation with defined inputs and outputs. It might read a calendar, post a message, update a ticket, call your HTTPS endpoint, or run code on one of your workers.

The definition makes calls consistent and inspectable. It does not guarantee the same result every time: credentials, external state, rate limits, network failures, and the supplied inputs can all change the outcome.

Open Library > Actions to see the organization's catalog. Ready means Mobius has the configuration needed to attempt the action. It does not prove that an external account, endpoint, or worker will succeed on the next call. Needs setup explains the missing connection or worker.

Where actions come from

Connecting a provider makes its catalog entries available, but each entry may need particular credentials, scopes, or provider setup. Read its Needs setup message instead of assuming that one connection enables every action.

Try a harmless action

This walkthrough uses the read-only platform action Runtime Context. It has no external account and does not change outside data.

1. Open Build > Agents and select an agent you can edit.
2. In Configure, grant it the Runtime Context action.
3. Open New chat with that agent and ask it: Call Runtime Context and show me the result.

In the reply, confirm that:

• the transcript shows a tool call to mobius.runtime.context;
• its result contains org_id and the session's own identifiers; and
• the turn finished rather than failing.

This proves that the catalog entry was ready, the agent could reach it, and the call and result were recorded in the transcript. It does not test an integration or a custom endpoint.

When you are finished, remove the action from the agent again. The transcript stays available for inspection.

Granting an action makes it a tool

An agent can only call actions you have granted it. Granting is what turns a catalog entry into a tool the model may choose during a turn.

The model decides whether and when to call it, which is why the grant is the control. Give an agent only the actions it needs, with the narrowest provider permissions and input schema you can use. An action's Read-only, Idempotent, and Destructive annotations describe expected behavior; they do not turn a mutating endpoint into a safe one.

Tool calls are not invisible. Each call and its result stay in the session transcript beside the agent's reply, so you can see what was sent and what came back.

For messages, writes, charges, deletions, or other external effects, instruct the agent to open an interaction and wait for approval before it calls the action. Withholding the action entirely is the stronger control when a wrong call would be expensive.

Inputs and results

The agent fills in an action's inputs from the action's input schema and what it knows in the turn. Mobius validates the declared shape; the receiving system remains responsible for its own business rules.

The response comes back to the agent as the tool result and stays in the transcript. Inspect a real result before you rely on its shape. A provider may return an empty value, a partial result, or a structured error, and an HTTP 202 response may mean only that another system accepted work rather than finished it.

Create a custom action

Create a custom action when Mobius needs to call an operation that is not in the catalog.

1. Open Library > Actions and select New action.
2. Enter an immutable Name using the dotted action-name format, such as tickets.search.
3. Add a clear Title and Description. Agents use these to decide whether the action fits their task.
4. Choose HTTP endpoint or Worker-backed.
5. Define the input and output with JSON Schema.
6. Set the behavior annotations accurately, then select Create action.

For an HTTP action, enter a public HTTPS Endpoint URL. Signed context is the default request-body format and includes authenticated organization, action, actor, and invocation details. Use Legacy only for a receiver that already implements the older body contract.

Mobius generates an HMAC signing secret when the action is created and shows it once. Store it in the receiving service's secret manager before leaving the page. The receiver must verify the signature over the exact request body and reject invalid signatures and replayed deliveries. The Actions API defines the body, signature headers, limits, and response behavior.

There is no dry-run button that makes an arbitrary endpoint harmless. Test a new receiver with a disposable, read-only operation and non-sensitive input. Verify both sides:

• the agent's tool call completed with the expected result; and
• Library > Actions > Recent invocations shows the action name, status, source, retry count, parameters, and output summary.

Only then add credentials or state-changing behavior.

A Worker-backed action has no endpoint URL or signing secret. A connected worker must advertise the exact action name and meet the action's location and capability requirements. If no eligible worker is active, the action cannot run.

Retries and irreversible effects

An action attempt can fail after the external system already performed the change, for example when the response is lost after a successful update. Treat a timeout or connection loss as an unknown outcome until you check the remote system.

For a change that supports idempotency:

• derive one stable key for the logical change;
• reuse that key for every retry of the same change;
• use a different key for different work; and
• confirm the provider's retention window and duplicate behavior.

Mobius retries cannot unsend a message or generally reverse a remote change. When a provider has no idempotency support, reconcile the remote state before retrying. Put an interaction before a high-risk change when a person must authorize it, but remember that approval does not make the provider call idempotent and does not undo an earlier effect.

Return application context to an agent

A signed custom HTTP action used as an agent tool can return named application context alongside its normal result. Mobius adds that context to the active agent turn so the model can see the updated application state on its next move.

This mechanism does not make a mutating tool safer. It only tells the agent what changed. Keep an interaction in front of the change itself when a person must authorize it. The Actions API defines the response media type, size limits, and SDK helpers.

Next

• Connect provider accounts with integrations.
• Give selected actions to an agent with tools and skills.
• Implement and verify custom receivers with the Actions API.
• Run action commands from the CLI command reference.