Threads and contexts
Understand which Agent settings, conversation history, project data, and files reach each thread.
A thread is one conversation with a saved Agent. Its context is assembled from several sources with different lifetimes.
Start a new chat with an Agent
In the Agents workspace, find the Agent in the left sidebar and select the + beside its name. You can also open the Agent and select New thread in the top right.
The new chat opens with that Agent's saved name, instructions, knowledge, Apps, and project. Send the first request as you would in an ordinary chat. For example:
"A customer says checkout is unavailable for their whole company. Classify the incident, list the missing details, and prepare the internal escalation. Do not contact anyone yet."
Use one thread for one case or outcome. Start another thread for a different customer, incident, or piece of work. This keeps the conversations separate while both can still use files and working memory from the Agent's configured project.
If you edit the Agent, start a new thread to test the change. A thread keeps the Agent setup it started with; it does not switch versions midway through a conversation.
Context map
| Source | Scope | What happens in a new thread |
|---|---|---|
| Agent definition | Saved Agent configuration | Captured when the thread starts |
| Conversation history | One thread | Starts empty |
| Agent knowledge files | Agent configuration | The configured list is captured at start |
| Project files | Configured project | Shared with other threads in that project |
| Project working memory | Configured project | Recent summaries can be recalled |
| Child task message | One child thread | Only the sent message is added, not the parent transcript |
The Agent definition includes its name, description, goal, instructions, allowed capabilities, project, and knowledge files. Editing that setup changes new threads. Existing threads keep the configuration they started with.
Ordinary chat context is different
Ordinary project chats can use global user preferences, project instructions, and context.md. Saved Agent threads use the Agent's saved definition instead. They can still use project files and working-memory summaries shared by the project.
Keep contexts isolated
What stays in one thread
- Its messages and attached-file references.
- In-progress turn state and temporary session data.
- The Agent definition captured when the thread started.
A new thread does not receive another thread's conversation history.
What threads can share
Threads started from the same Agent can use the same knowledge files and capabilities. Threads in the same project can also use its files and short working-memory summaries. If two threads edit the same resource at once, their changes can conflict.
When to start a new thread
Start one when the topic or customer changes, when a task needs its own history, or when independent work can progress separately. Keep the current thread when the next step depends on its full conversation.
Use parent and child threads
A top-level Agent thread can create direct child threads for separate tasks. Each child receives a bounded task and works in its own conversation. The hierarchy has one level: a parent can create several children, but a child cannot create another child.
Choose when children are created
| Setting | Behavior |
|---|---|
| Off | The Agent cannot manage other threads. |
| Explicit | The Agent creates a child only when you ask or its instructions require one. This is the default. |
| Proactive | The Agent may create direct children for distinct tasks that can progress independently. |
Give a child enough context
A child sees the task message, not the parent's transcript. Include the task, source material, constraints, approval boundaries, and expected result. Its final result returns to the parent automatically; only the parent that created it can send follow-up work, cancel it, or delete it.
Work in parallel safely
Use separate children for read-only research or changes to different outputs. Keep changes to the same files or shared APIs in one thread, then combine the work there.
Pick the right scope
- Put stable Agent behavior in Instructions.
- Put read-only reference material in Agent knowledge files.
- Put finished and working files in the configured project.
- Start a new thread for a clean conversation.
- Use a child thread only when the task can progress with the context you send it.
Related guides
Read Project context and User preferences for the remaining context boundaries. See Threads and messages for the public thread API.