Sessions and versions
An agent has two kinds of continuity. A session keeps one piece of work together. A version records the setup the agent uses to do that work.
The distinction matters when you return to an agent and ask: what does it know from last time, and what changed in how it works?
A session keeps one conversation together
Imagine using the marketing launch agent to prepare Monday's campaign report. During that session, you ask it to compare results, investigate a weak audience, and shorten the final summary. The messages, tool activity, and working files all belong to that conversation.
Starting a new session gives you a clean conversation. The new session does not automatically include Monday's discussion as context. It still starts with the agent's working setup: its instructions, skills, tools, permissions, model, and agent files.
This makes sessions useful boundaries. You can keep one campaign review focused without mixing it with last week's launch or another teammate's task.
Shared files can carry useful knowledge forward
A clean conversation does not mean every useful result must disappear.
Suppose Monday's review reveals that the team has already used one of the campaign topics. Save the approved content inventory in the agent's files and tell the agent to check it before proposing new topics. A later session can read that shared file even though it does not inherit Monday's conversation.
The difference is simple:
| Scope | What it keeps together | Campaign example |
|---|---|---|
| Session | One conversation and its current work | Monday's questions, tool activity, and uploaded spreadsheet |
| Agent | Reusable setup and shared files | The reporting skill, brand guide, and approved content inventory |
Use the session for what the agent needs now. Put durable reference material in the agent's files when future sessions should be able to use it.
A version records a change to the agent
Now update the launch agent's instructions: before suggesting a topic, check the approved content inventory. When you commit that change, Agenta saves a new version.
A version is a numbered snapshot of the agent's configuration. It records changes such as:
- Revised instructions.
- A skill or tool added or removed.
- A different permission setting.
- A new model or harness choice.
- Updated agent files.
The next session can begin with the improved version even though its conversation starts clean.
Sessions show what happened; versions show what changed
On Tuesday, the agent avoids the repeated topic. Two different histories help explain why:
- The session shows what the agent received, which tools it used, and what it returned during Tuesday's work.
- The version history shows the configuration change that told it to consult the content inventory.
This separation helps when behavior changes. First inspect the session to understand the run. Then check the agent's versions in the Registry to see whether its setup changed.
Committing a new version does not rewrite past sessions. It gives later work a recorded configuration to run from. Automations can also pin an exact version so a future scheduled or event-driven run keeps using the setup you selected.
Continue with the guides
- Write your agent's instructions shows how to make and commit a configuration change.
- Files and knowledge explains the difference between session files and shared agent files.
- Automations explains why scheduled and event-driven runs use a pinned version.
- Cost and usage explains how work within a session becomes recorded usage.