Learn how to run a context agent, read its output, change its settings, put it on a daily, weekly, or monthly schedule, and delete it.
Run and schedule agent Private Preview
Once an agent exists, you run it, read what it proposed, adjust its settings, and put it on a schedule, so your glossary stays current as your documentation changes.
Asset ↔ Term Linker agents can't be scheduled, and publishing writes the links a sample proposed rather than deciding again. See Link terms to assets for how they run.
Prerequisites
Before you begin, make sure you have:
- Workspace admin or governance admin access
- An agent that already exists. See Create an agent from a template
Open an agent
- In your Atlan workspace, click Agents from the left sidebar.
- Click the agent you want to work with.
The agent page shows the number of runs, the sources it can reach, and its active version, with four tabs: Overview, Runs, Versions, and Settings.
Run an agent
Two buttons sit at the top right of the tab strip.
| Button | What it does |
|---|---|
| Sample run | Reads part of your sources for real and writes nothing. Starts immediately. |
| Full run | Publishes to your glossary. Opens a confirmation showing the sources, scope, and instructions it's about to use. |
An agent runs one at a time. Both buttons are unavailable while a run is in flight.
Always sample first. A sample run publishes nothing and takes a minute or two, so it's the cheapest way to check your instructions before writing to your glossary.
Read a run
Select the Runs tab, then pick a run. The most recent is badged Latest.
Each run reports a status:
| Status | What it means |
|---|---|
| Running | In progress |
| Succeeded | Finished and did its work |
| Degraded | Finished, but something isn't right. The reason is named on the run |
| Failed | Didn't finish |
| Stopped | Someone stopped it. Neither an error nor a success |
Alongside the status you get the duration, the number of terms sampled or published, and the credits consumed.
The instructions that run used are shown underneath. This matters once you have edited them a few times: you are reading what this run was told, not what the agent is currently configured to do.
Sample preview lists what the run proposed. Each term shows its name, whether it's created or enriched, the proposed definition, and an expandable Sources block with the citation behind it. After a full run, the same panel shows what was published, with the sources attached to each term listed under it. Selecting a source opens it in a new tab. View in Atlan opens the glossary.
Stop a run
While a run is in flight, Stop appears on the run's stats card. Selecting it asks you to confirm, then ends the run.
A stopped run reports Stopped, with the note "Stopped by the user. Anything it published before stopping is still in Atlan."
Stop is a termination, not an undo. Two consequences:
- The run stops at its next step, so it may keep working for a moment after you confirm.
- Anything the run had already published stays in Atlan. If a full run wrote terms you didn't want, you have to delete them yourself. There is no un-publish and no automatic cleanup.
This is the main reason to use a sample run first: a sample publishes nothing, so stopping one leaves nothing behind.
Iterate on sample
After a sample run, read the proposed terms and ask whether they're the right concepts, at the right level, defined the way your organisation defines them. If not, change the run instructions or the scope and sample again.
A full run re-derives everything from scratch rather than publishing the rows you just reviewed. Treat a sample as a signal about your instructions, not a shortlist to approve. Because a sample skips the duplicate check against your existing glossary, almost everything in it shows as new, while a full run may enrich existing terms instead.
Usage reporting
To review agent activity across a month rather than run by run, open the usage reporting view in Agent Studio. It shows a month-level summary of agent usage, and you can drill down from the summary into the individual runs behind it.
This replaces the earlier reporting view, which listed a high-volume stream of updates. If you used that view to see what agents did recently, use the month-level summary instead, then drill into individual runs for the detail. Each drill-down run opens in the same shape documented under Read a run.
Change agent settings
Select the Settings tab. What you can change, and what it costs:
| Field | Effect |
|---|---|
| Run instructions | Takes effect on the next run. No new version. |
| Where to look? | Takes effect on the next run. No new version. |
| Sources | Creates a new version, which then serves every run. |
| Skills | Creates a new version. |
A linker agent has no Sources or Where to look?. Its Settings show Terms and assets instead, where you change its glossaries and asset collection. Saving a change there creates a new version, which then serves every run. See Change glossaries or collection.
Name, description, and the template can't be changed after creation.
Settings are standing configuration. There is no per-run override, so change the setting and then run.
Why some changes create versions
Widening or narrowing what an agent can reach changes its access, so it's recorded as a version. Retargeting where it looks inside what it can already reach, or changing what you are asking for, isn't.
The Versions tab records what each version can reach, who changed it, and when. One version is active at a time.
Schedule an agent
You can set a schedule from the Settings tab, or from the chevron beside Full run. The fields are the same either way.
- Under Runs every, choose Day, Week, or Month.
- Set Run starts at and Timezone.
- Check the read-back sentence, for example
At 00:00, every day (Asia/Calcutta). - Click Schedule agent.
From the run button, the panel also shows the exact sources, scope, and instructions each scheduled run uses, with a link to change them.
A schedule is a standing instruction to write to your glossary on a cadence, exactly like clicking Full run. There is no scheduled sample run.
You must complete one successful sample run before you can schedule an agent, so that nobody schedules an agent whose output they have never seen.
Schedules can be paused, resumed, and removed. A paused schedule doesn't run again until you resume it.
What scheduled runs read
A scheduled run doesn't re-read everything each time. Atlan tracks the state of your source, using commit and page timestamps since the last run, and processes only what changed. That's what makes a schedule useful on a source your teams keep writing to: the first run does the bulk of the work, and each run after it catches up.
Three things to expect:
- If a scheduled run is still going when the next one is due, the new one is skipped rather than queued. Fewer runs than your cadence implies usually means the previous run was still working.
- If you schedule several agents, stagger their start times. Agents share run capacity across your tenant, so a dozen agents all set to 00:00 queue rather than run together.
- A scheduled run has a time budget. If it doesn't finish within it, the run is stopped, and anything it published before stopping stays in Atlan. The run reports the reason it stopped.
Delete agent
Only admins can delete an agent.
- Open the agent and select the Settings tab.
- Scroll to Delete agent at the bottom of the page and click Delete agent.
- Read the confirmation. If the agent has schedules, it lists each one as active, with its next run time, or paused.
- Select I understand the risks, delete the agent., then click Delete.
The agent disappears from Agents studio, and you're returned to the studio home.
Deleting an agent removes:
- The agent and its configuration
- All of its schedules, active or paused. No further scheduled runs happen
- Its run history in Agents studio
Deleting an agent doesn't remove anything it already wrote to the catalog, such as glossary terms, definitions, descriptions, or term links. Those stay in Atlan and still carry the isAIGenerated tag, so you can find and review them later.
There is no restore for a deleted agent. To get it back, create a new agent from the template, which starts with no run history.
Need help
If you need assistance after reviewing this page, contact Atlan support.
See also
- Write run instructions: what to change between samples
- FAQ - Agent templates: retries, undo, deleting an agent, and other run behaviour
- Understand agent templates: what a run writes and where