Shortcuts and quick actions
Ask the active agent for a reply or dispatch a selected agent from macOS Shortcuts.
In this topic
macOS Shortcuts can ask your active Mellow agent a question or start a selected agent's background task. Choose the action based on whether the shortcut needs an answer immediately or should hand work to Mellow and continue.
The two actions
| Action | Input | What the shortcut receives |
|---|---|---|
| Ask Mellow | Prompt | The active agent's reply as text, with a dialog result |
| Run Mellow Agent | Selected agent and optional input | Confirmation that the background dispatch started |
Ask Mellow uses whichever agent is active. For a repeatable workflow tied to a particular specialist, use Run Mellow Agent and select that agent explicitly.
Before you start
Open Mellow and check that the intended agent can complete a normal message using its selected model. The actions use Mellow's local server, so a saved shortcut does not replace app, server or provider setup. Any tools the task needs must be available to the agent.
Get started
- Open Apple's Shortcuts app and create a shortcut.
- Search the available actions for Mellow.
- Add the action matching your goal.
- Supply a short prompt, or choose an agent and input.
- Run the shortcut and inspect the result in both Shortcuts and Mellow.
For a first test, ask for a two-sentence summary of text you supply. Avoid making a long tool-running task your first synchronous test.
Build a useful workflow
A text-processing shortcut can collect input, pass it to Ask Mellow, and use the returned text in the next action. Keep the request small enough to finish within the system's intent time budget.
For longer work, choose Run Mellow Agent. Its confirmation means the task was dispatched; inspect Mellow's Work view for completion and results. Do not pass that confirmation to a later action as though it were the finished answer.
An example background instruction is: “Review the notes available in this project and prepare three questions for tomorrow's planning session.” Configure the agent's project or tools beforehand; mentioning a folder in a shortcut does not grant access to it.
Spotlight and Siri
Mellow declares app shortcuts so the operating system can expose them through Shortcuts, Spotlight and Siri. The registered phrase Ask Mellow supplies the prompt through the intent parameter. Agent shortcuts can select an agent entity. Availability and presentation depend on macOS indexing and system settings.
Under the hood
The immediate-answer action follows the streaming /agents/{id}/run path. Its connection is tied to the intent: heavy tool use can outlive the intent budget and the connection-bound run can be cancelled.
The background action uses /agents/{id}/dispatch. It is detached from the shortcut's return, allowing progress and results to surface in Mellow afterward. See HTTP API for the distinction between waiting on a run and dispatching work.
Troubleshooting
| Problem | Check |
|---|---|
| Mellow actions are absent | Launch the installed app, then search Shortcuts again |
| Wrong agent answers | Ask Mellow follows the active agent; use explicit agent dispatch if needed |
| No model can answer | Verify the agent's model in a normal chat |
| Long request times out | Use background dispatch and inspect Work for the result |
| “Started” appears but no final answer | This is a dispatch receipt; review the run inside Mellow |
| Tool cannot access a resource | Configure the agent's permissions and connection in Mellow |