Agent session

What is an agent session?

An agent session is one running instance of an AI agent. It has its own conversation history, its own working files, the tools and permissions it was granted, and a lifetime that starts when someone hands it work and ends when someone or something closes it. Two colleagues asking the same agent two different questions get two sessions, not one agent juggling both.

The concept exists because the model underneath holds nothing. A model API is stateless: every request arrives with no history attached, and the model forgets the lot the moment it answers. So everything that makes an agent feel continuous, the fact that it knows what you asked two minutes ago and that the file it wrote is still where it left it, is state that something outside the model is keeping. The session is where that state lives.

Anthropic sums it up in one line in its Managed Agents documentation: a session is a running agent instance within an environment, performing a specific task and generating outputs. Microsoft says the same thing from the infrastructure side: a session ID identifies a logical session with persisted state, including the agent's home directory. A session is closer to a desk than to a person, with the papers of one job on it and a name plate that turns up in every log line about that job.

What a session holds

• The message history. Every user message, every model turn, every tool call and its result, in order. This is what gets resent to the model on each turn, so it is also the part that costs money.

• The working files. Microsoft gives each hosted session a persistent $HOME, keeps it when the compute is deprovisioned and restores it when the session resumes. Anthropic scopes the files a session produced to that session.

• The tools and permissions for this run. Anthropic lets you change a session's tools and MCP servers mid-run, and those updates stay session-local: they do not propagate back to the underlying agent. Credentials work the same way, through vault IDs you pass at creation. What this agent was allowed to do is a per-session answer.

• An identifier that ties the transcript, the files, the bill and every log line to the same piece of work.

Vendors name the same thing differently. Anthropic says session and calls what flows through it events. OpenAI calls the durable object a conversation. Google's Agent Development Kit calls it a Session, one conversation thread between a user and your agent. Microsoft splits it in two: the session ID owns the compute and the files, while the conversation ID is a durable record of history that persists independently of compute state. Two objects, two lifetimes, one platform, which is why you ask how long something is kept per object rather than per product. A run is none of those. A run is one execution against the session, and a session holds many.

From the first message to deletion

Starting. A session begins when someone sends a first message, when your code creates one, or when a schedule fires. Microsoft's platform creates it on first use and provisions a sandbox.

Going idle. Idle means the agent is waiting for you, not that it is finished. Anthropic's statuses are idle, running, rescheduling and terminated, and a session that completes its work goes idle rather than terminated. Idle is where the meter stops: session runtime costs $0.08 per session-hour and accrues only while the status is running. Microsoft bills the CPU and memory of active sessions and deprovisions compute after an idle timeout you set between 5 and 60 minutes, 15 by default, keeping the files.

Resuming. Reference the same session ID and the platform restores the state onto fresh compute, so someone can walk away from a piece of work and pick it up later.

Ending. This is the edge people get wrong. Anthropic separates archiving, which blocks new events but keeps the history, from deleting, which permanently removes the session's record, its events and its sandbox. Memory stores, vaults and files you uploaded survive that; files the session itself produced go with its filesystem. Microsoft's hosted agents delete a session permanently after 30 days of inactivity. Download what you want to keep before you delete, and find out what your platform's inactivity clock is.

One support session end to end

A support agent runs on Claude Sonnet 5 inside your helpdesk. Anna opens ticket 2026-1184 at 09:12 and asks why a customer was charged twice.

1. 09:12, created. A session opens under Anna's identity, with an ID, an empty working directory and this agent's tools: read access to the invoicing database and the payment provider, plus one write tool that saves a draft reply.

2. 09:12 to 09:19, running. Six model turns. It pulls both payment records, finds a retry that was booked twice, and writes a small file listing the customer's last twelve payments. That file exists in the session and nowhere else.

3. 09:19 to 09:27, idle. The write tool needs a confirmation and Anna is on the phone. Nothing runs, so no runtime is billed.

4. 09:27 to 09:34, running, then idle. Anna confirms, the draft lands on the ticket, and the agent produces a final turn with no tool call in it.

The bill. The session sent about 180,000 input tokens across those turns, because every turn resent everything before it, of which 140,000 were cache reads, plus 12,000 output tokens. At Sonnet 5 rates that is $0.08 for the 40,000 uncached input tokens at $2 per million, $0.03 for the cache reads at $0.20 per million, and $0.12 for the output at $10 per million. Runtime ran 14 minutes, so 14/60 of an hour at $0.08 adds $0.02. Around 25 US cents, and the eight idle minutes cost nothing.

What survives. The draft reply does, because a tool call wrote it into the helpdesk. The file of twelve payments does not, because it only ever existed in the session's filesystem. The transcript stays on Anthropic's side until somebody deletes the session. And tomorrow the agent knows nothing about this customer, because nothing was written to a memory store.

An agent session versus agent memory

These two get confused constantly, and one question separates them: what still exists tomorrow?

A session is a workspace with an end date. It holds the whole conversation and every file the agent touched, which makes it feel like an excellent memory as long as you are inside it. Close it and by default all of it goes.

Memory is what somebody chose to write down. A line in a memory file, a row in a customer table, a fact in a vector store. It is there tomorrow because a deliberate write put it somewhere the session does not own.

An agent that forgot your project overnight is therefore behaving as designed. The same logic settles how you handle long work: a task that outlives a session, an approval sitting for three days or a migration running across a weekend, needs its state written somewhere with a longer life than the session has.

What to watch out for with agent sessions

A session leaking between users is a defect, not a quirk. Microsoft's guidance for hosted agents is blunt: route two users to the same session and they can see each other's data. The platform scopes sessions to the caller's identity by default, and when your own application authenticates its users you pass an identifier per user, which the docs insist you derive server-side and never from a value the browser supplies.

Cap the runaway at the session. Claude Managed Agents accepts a budget when you create a session and pauses it with the stop reason budget_reached once the cap is reached. Set one for anything running unattended, because the session is also the thing you can stop.

The session ID is your incident report. When a customer says the assistant told them something wrong, you want one identifier that pulls up the transcript, the tool calls, the files and the spend. If your logs record users and days but not sessions, every investigation starts with a search.

Answer the retention question per feature. Anthropic states that Managed Agents is not eligible for zero data retention, because sessions are stateful resources whose transcripts persist until you delete them. OpenAI keeps response objects for 30 days by default while conversation objects sit outside that clock. Two features from one company answer differently, so ask about the one you are using.