> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Run an agent on demand
> Trigger a Corti agent from dictation to transform the current text — e.g. an on-demand copy-edit pass
**Follow along with the runnable example.** This guide walks through the [on-demand agent example](https://github.com/corticph/corti-examples/tree/main/sdk/typescript/applets/src/applets/on-demand-agent) in `corti-examples` — bootstrap your build from it or use it as reference.
Once text is in the editor, you can hand it to a [Corti Agentic Framework](/agentic/overview) agent for a transformation the speech-to-text model doesn't do — for example a minimal **copy-edit** pass that fixes spelling, grammar, and punctuation without changing wording or meaning. The user triggers it *on demand*, then the result replaces the editor's content.
This guide combines the [Commands](/stt/guides/dictation-commands) trigger pattern with the [Agentic Framework](/agentic/quickstart).
The prompts used here are mere examples - be sure to test and refine the prompt to support your specific needs.
***
## Ensure the agent exists
An agent is created once by name and reused. Look it up in `client.agents.list()`; create it if missing. See the [on-demand agent example](https://github.com/corticph/corti-examples/tree/main/sdk/typescript/applets/src/applets/on-demand-agent) in `corti-examples` for the full `ensureAgent` implementation. The agent's behavior lives entirely in its `systemPrompt`:
```ts title="Copy-edit system prompt" theme={null}
const COPY_EDITOR = {
name: "Dictation Copy Editor",
description: "Minimal spelling, grammar, and punctuation copy-editor for dictated text.",
systemPrompt: `You are a meticulous copy editor for dictated clinical text.
Apply ONLY the minimal spelling, grammar, capitalization, spacing, and punctuation corrections needed to make the text readable.
Do NOT reword, rephrase, summarize, expand, or remove content. Do NOT change clinical meaning, numbers, units, or medication names.
Preserve line breaks and structure.
Return ONLY the corrected text — no commentary, labels, or quotation marks.`,
};
```
Cache the returned agent id per **API client** (e.g. keyed by `clientId:tenant`) so you don't list/create on every run. Because behavior is prompt-driven, you can change what the agent does by updating its `systemPrompt` — no code change.
***
## Trigger it on demand
Expose the action as a voice command (and/or a button). Declare a `copy_edit` command with phrases like `"copy edit"`, `"clean up text"`, or `"polish text"` in your `dictationConfig.commands`, then call `runAgent(adapter)` when that command fires. See the [Commands guide](/stt/guides/dictation-commands) for the declare → event → dispatch pattern.
***
## Run the pass and write back
Send the editor's current text as a single isolated message (no `contextId` — each run stands alone), then replace the editor content via the [`EditorAdapter`](/stt/guides/dictation-text-insertion#write-insertion-logic-once-with-an-adapter) with the result. See the [on-demand agent example](https://github.com/corticph/corti-examples/tree/main/sdk/typescript/applets/src/applets/on-demand-agent) in `corti-examples` for the full `messageSend` and write-back implementation.
Guard the write-back: if the agent returns an empty response, leave the user's content untouched. When a copy-edit agent has nothing to fix, it returns the text unchanged — so writing the result back is safe either way, but an empty result must never clear the editor.
***
## Next steps
What agents are, how to create them, and the message API.
Run an agent automatically over a finalized transcript.
The complete, runnable on-demand agent example in `corti-examples`.
Please [contact us](mailto:help@corti.ai) for help or questions.