Skip to content

Run Actions

Actions are typed operations the agent serves: a Python function with a JSON Schema for its parameters, exposed under a name. Anything that's been registered — your own @action-decorated functions, an extension's actions — can be listed, inspected, and run from the same agent.

Defining your own actions?

This page covers calling actions. To expose your own Python functions as actions, see How to Use Actions.

The snippets below assume an agent connected via connect():

from zelos_sdk.agent import connect

with connect() as agent:
    ...

Examples use placeholder names like "my_app/read_voltage". Substitute your own from agent.actions.list().

List actions

for info in agent.actions.list():
    print(info.name)
# my_app/read_voltage
# my_app/restart_service
# ...

ActionInfo.name is what you pass to schema() and execute(). Names usually include a namespace prefix, so actions from different sources sit alongside each other.

Run an action

result = agent.actions.execute("my_app/read_voltage", {"rail": "5v0"})

if result.ok:
    print(result.value)         # 5.02
else:
    print(f"action returned status={result.status!r}: {result.value}")

The result is an ActionResult:

  • .value — the return value as native Python (None, bool, int, float, str, list, or dict).
  • .status — "pass" or "done" (success), "fail" (logical failure), or "error" (the action raised).
  • .ok — True when status is "pass" or "done". Always check .ok before reading .value.

The signature is typed -> Optional[ActionResult] because the proto field is wire-optional, but current agent versions always populate it — defensive code may guard if result is None: ..., but in practice you can rely on a non-None result.

For no-arg actions, omit params or pass None:

result = agent.actions.execute("my_app/restart_service")

Most actions reject unknown fields with a "fail" status — the schema is the source of truth for what params should contain.

Timeouts

timeout is a float in seconds. None (default) defers to the agent's 30-second default — not unbounded. For long-running actions, pass a value larger than the action's expected duration.

result = agent.actions.execute("my_app/long_calibration", timeout=60.0)

Inspect a schema

agent.actions.schema(name) returns an ActionSchema describing the action's inputs:

Field Description
.action_schema A JSON Schema dict — types, required fields, ranges, patterns.
.ui_schema UI hints (widget choices, ordering). Optional; ignore if you're calling directly.
.default_timeout_ms The action's preferred timeout in milliseconds, or None. Informational. 
schema = agent.actions.schema("my_app/read_voltage")

print(schema.action_schema["required"])
# ['rail']

The schema tells you exactly what params should contain.

Dynamic schemas

For schemas where one field's choices depend on another, pass current_values= with whatever the user has filled in so far. Same JSON-friendly dict shape as params.

Build a UI from a schema

action_schema is standard JSON Schema, so it drops into any form library that consumes it (the Zelos App uses react-jsonschema-form). To inspect fields directly:

schema = agent.actions.schema("my_app/read_voltage")
for name, field in schema.action_schema.get("properties", {}).items():
    title = field.get("title") or name
    print(name, field.get("type"), "-", title)

Errors

from zelos_sdk.agent import ActionFailed, AgentError

try:
    result = agent.actions.execute("my_app/read_voltage", timeout=5.0)
except ActionFailed as exc:
    print("action raised:", exc)
except AgentError as exc:
    print("call failed:", exc, "cause:", exc.cause)
else:
    if not result.ok:
        print(f"action reported {result.status!r}: {result.value}")
    else:
        print(result.value)
Exception When
ValueError The action name is empty or not a string.
AgentError (with cause=None) params or current_values aren't JSON-serializable.
ActionFailed The action raised an exception the agent couldn't categorize, or returned an unrecognized status.
Internal The agent returned a result the SDK couldn't decode (rare).
AgentError Catch-all parent. .cause has extra detail when available.

A failing action result (status="fail" or "error") does not raise — check .ok.

Tips

  • Pass params=None (or omit it) for no-arg actions.
  • Always check result.ok before reading result.value. A "fail" or "error" status often puts a diagnostic message in value.
  • default_timeout_ms is informational — the SDK doesn't apply it automatically. Pass it as timeout= if you want it.

What's next