# Run an action

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

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](/docs/vision/connectors/connect). 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:

```sh
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:

```sh
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:

```sh
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:

- [Use a browser](/docs/vision/browser-computer/browser-use).
- [Use your computer](/docs/vision/browser-computer/computer-use).

## 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:

```sh
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](/docs/vision/autopilot/long-running-tasks) 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](/docs/vision/settings/troubleshooting) to resolve the specific failure.
