Skip to content

For the complete documentation index, see llms.txt. Markdown versions are available by appending .md to documentation page URLs. Read the agent handbook.

Zortex Docs
Start searching Install Vision
Run an action

Run an action

Read or change a connected app using the operation it actually exposes, then check the result.

On this page

An action can read current information, change an app, operate a browser, or create a share. Use the method's current schema and the account intended by your task.

Before you run it

Check the source with zortex manage --json '{"what":"sources"}'. If necessary, connect the service. Make sure the target account, resource, and permitted effect are clear. Existing authorization for the task carries through its ordinary steps; inspecting a schema does not create an extra confirmation requirement.

Read through a shared action

For a small Gmail read:

Shell
zortex action --json '{"name":"connector.read","params":{"source":"gmail","request":{"limit":5}}}'

This uses a shared action name and its params object. A success can legitimately contain no records. Read the response rather than treating an empty list as an authentication failure.

The equivalent MCP request is:

Text
indra.action({"name":"connector.read","params":{"source":"gmail","request":{"limit":5}}})

Run a provider-specific method

First discover and inspect the method:

Shell
zortex actions --json '{"source":"<source-id>"}'
zortex actions --json '{"source":"<source-id>","method":"<returned-method-name>"}'

Then invoke it through connector.invoke. This is an input template; replace the placeholders and fill input.params with the fields required by the returned schema:

Shell
zortex action --json '{"name":"connector.invoke","params":{"source":"<source-id>","method":"<returned-method-name>","input":{"params":{}}}}'

input.params is required even when the chosen method has no parameter fields. Include input.body or input.media only when that method's schema calls for them. Do not add a guessed confirm, dryRun, or account field.

For a write, obtain the target object's current identity and content first. Apply the requested change, then read the same object again or inspect its visible state. A returned object or job reference tells you what to inspect; it is not a substitute for the requested outcome.

Browser and computer actions

Browser methods such as browser.open are shared action names and can be called directly through action. Desktop methods discovered from cua use connector.invoke. Their guides include the full sequence:

Handle the returned state

Response or observation What to do
Successful read with records Inspect the relevant contents and retain their identities.
Successful empty read Report the exercised scope and empty result; widen only if the task calls for it.
Returned authorization job Keep its ID and poll connector.job; continue the existing connection.
Returned browser continuation Observe and continue the same browser session using its current controls.
err with input/schema problem Correct the named argument from the current method schema.
err with missing authentication Recover the intended source/account and retry the bounded operation.
Write timed out or its outcome is unknown Read the target's current state before deciding whether to retry.

For an authorization job returned by a connection action:

Shell
zortex action --json '{"name":"connector.job","params":{"id":"<returned-job-id>"}}'

That command polls connection jobs; it is not a universal task-status API. Follow long-running work explains the other owners of progress.

Verify completion

Check the business result: the intended document changed, the requested object exists, the selected information was read, or the page shows the expected effect. A queued operation, successful process exit, or available catalog alone cannot establish that.

If the result remains uncertain, preserve the returned identity and the last confirmed state. Do not repeat a potentially completed send, upload, or edit to make the output look successful. Use Troubleshooting to resolve the specific failure.

Suggested