Skip to content

Commit 4c5fade

Browse files
olguzzarolguzzar
authored
Merge pull request #9617 from olguzzar/academy-foundations
Foundations Course
2 parents e7fb411 + 5893ffc commit 4c5fade

30 files changed

+953
-14
lines changed

‎learn/foundations/agent-sessions-and-where-agents-run.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
ContentId: 9a8f0a40-f4f9-4d2b-b7b2-c1d54ef4c004
3+
DateApproved: 03/30/2026
4+
MetaDescription: Manage agent sessions in VS Code across local, background, and cloud execution modes, and choose the right agent type.
5+
MetaSocialImage: ../images/shared/agent-first-development-social.png
6+
---
7+
# Agent sessions and where agents run
8+
9+
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/0CsKOO7d35I?si=z020p9GwioCzmOH4" title="Video for agent sessions and where agents run." frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
10+
11+
As you work with agents, you accumulate multiple sessions across different features, bug fixes, and explorations. You also want to run several agents simultaneously - one working interactively while another handles background tasks, for example. This guide covers how to navigate and manage agent sessions, and the difference between the three places an agent can run, locally in VS Code, in the background with Copilot CLI, and remotely in the cloud on GitHub infrastructure.
12+
13+
## The agent sessions sidebar
14+
15+
The Agent Sessions sidebar is your control center for everything happening across your agents. Open it from the VS Code activity bar, or select **Show Agent Sessions Sidebar** at the top of the Chat view.
16+
17+
![Screenshot of the Agent Sessions sidebar in VS Code, showing agent sessions with their names, timestamps, and pending file changes.](../images/foundations/agent-sessions-sidebar.png)
18+
19+
The sidebar lists every session you have worked in. Each entry shows:
20+
21+
* The session name.
22+
* A timestamp for when it was last active.
23+
* A file change count if the agent made changes you have not reviewed yet. This clears once you accept or undo them.
24+
25+
![Screenshot of the Agent Sessions view in VS Code, showing agent sessions with their names.](../images/foundations/sessions-view.png)
26+
27+
Select any session to open it in the Chat view. The full conversation history is there, exactly where you left it. Every session is independent, with its own context window, conversation history, and tool results. What you do in one doesn't affect any other.
28+
29+
### Running multiple agents in parallel
30+
31+
You do not have to finish one session before starting another. Start a new session, and the previous one keeps working in the background.
32+
33+
This lets you run multiple agents at once.
34+
35+
* A local session for interactive debugging.
36+
* A background agent for refactoring a test suite.
37+
* A cloud agent for writing documentation.
38+
39+
If you want to watch more than one session at once, move a session into an editor tab or separate window.
40+
41+
### Managing sessions
42+
43+
Right-click any session for management options.
44+
45+
* Archive hides the session from the active list but keeps it intact so you can search for it and reopen it later. Use this to declutter without losing history.
46+
* Delete removes the session permanently. Use this only when you're certain you don't need it.
47+
48+
## The agent type picker
49+
50+
At the bottom of the chat input is the agent type picker. It shows the current agent type and controls where the next session runs.
51+
52+
In a fresh session, it shows the available agent types. In an active session, it shows options to start a new session or hand off the current one to a different agent type.
53+
54+
![Screenshot of the agent type picker in VS Code, showing options for choosing where the agent runs and handing off between agent types.](../images/foundations/agent-type.png)
55+
56+
## Local agents
57+
58+
Local is the default agent type. The agent runs interactively inside VS Code with access to your workspace, tools, and terminal.
59+
60+
Use Local when you want to:
61+
62+
* Work hands-on and iterate quickly.
63+
* Stay in control of each decision.
64+
* Do interactive debugging or exploratory development.
65+
66+
## Copilot CLI (background agents)
67+
68+
Copilot CLI runs the agent as a background process on your machine while you keep working in the editor. You can run multiple CLI sessions in parallel.
69+
70+
CLI sessions show up in the Agent Sessions sidebar alongside local sessions - one place to view everything.
71+
72+
Copilot CLI will be covered in depth in a later section of this series.
73+
74+
## Cloud agents
75+
76+
Cloud agents run on GitHub infrastructure, off your machine entirely. A cloud agent will create a pull request, push commits as it works, and leave the result ready for review.
77+
78+
This is the fully asynchronous option. You can close VS Code, come back later, and review the work in the pull request.
79+
80+
Use cloud agents for tasks that are:
81+
82+
* Well-scoped with a clear done state.
83+
* Suitable to hand off completely.
84+
* Naturally suited to team collaboration via pull requests.
85+
86+
### Starting a cloud agent session
87+
88+
In a fresh session, select **Cloud** in the agent type picker.
89+
90+
Here is an example prompt.
91+
92+
```prompt
93+
Add a README documenting the base62 encoder, what it does, how to run it, and examples of encoding and decoding from the command line.
94+
```
95+
96+
The agent spins up on GitHub infrastructure for you, creates a draft pull request, clones the repository, reads the code, and starts pushing commits.
97+
98+
### Viewing cloud agent sessions
99+
100+
If you have the [GitHub Pull Requests extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) installed, the pull request shows up inside VS Code.
101+
102+
On GitHub.com, your repository's Agents tab shows active sessions, their status, and the linked pull request. You can open a session there to inspect its step-by-step log and send follow-up guidance mid-run.
103+
104+
## Handing off between agent types
105+
106+
In an active session, the agent type picker shows two options.
107+
108+
* New Chat Session starts a fresh session with an empty context window.
109+
* Continue In hands off the current session to a different agent type and carries the full context forward.
110+
111+
Use Continue In when you want to start locally, then hand the work off to a background or cloud agent without rebuilding context from scratch.
112+
113+
## Choosing the right agent type
114+
115+
| Situation | Best choice |
116+
| --- | --- |
117+
| Interactive, hands-on development | Local |
118+
| Several independent tasks in parallel | Copilot CLI |
119+
| Well-scoped task to hand off as a pull request | Cloud |
120+
| Exploratory work where you want to stay in the loop | Local |
121+
| Async work to review later | Cloud |
122+
123+
## What's next
124+
125+
The Agent Sessions sidebar gives a complete view of work happening across agent types. Local for interactive work. CLI for parallel background tasks. Cloud for fully async work that produces a pull request.
126+
127+
In the [next guide](debugging-and-whats-happening-behind-the-scenes.md), you will go behind the scenes and inspect prompts, tool calls, and responses to understand what the agent is doing.
128+
129+
## Learn more
130+
131+
* [Using agents in VS Code](https://code.visualstudio.com/docs/copilot/agents/overview)
132+
* [GitHub Pull Requests extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github)

‎learn/foundations/approvals-autonomy-and-context-budget.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
ContentId: 9a8f0a40-f4f9-4d2b-b7b2-c1d54ef4c002
3+
DateApproved: 03/30/2026
4+
MetaDescription: Manage approvals, autonomy, and context budget for coding agents in VS Code, including scoped approvals and compaction.
5+
MetaSocialImage: ../images/shared/agent-first-development-social.png
6+
---
7+
# Approvals, autonomy, and context budget
8+
9+
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/WcN74XvZGes?si=OCbyVFSsIskUnHga" title="Video for approvals, autonomy, and context budget." frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
10+
11+
Every action an agent takes on your machine, running a command, writing a file, or launching a server, happens through its tools. By default, terminal commands require explicit approval before they run. This guide covers how approvals work, how to set the right autonomy level for a session, and how to monitor context budget as work builds up.
12+
13+
## Understanding tool call approvals
14+
15+
When the agent wants to run a terminal command, it shows an approval dialog with the exact command it intends to run. Review it. If it looks right, approve it. If something looks off, select **Skip** and send a message to correct the direction.
16+
17+
### Scoped approvals
18+
19+
The approval dropdown gives fine-grained control over how broadly an approval applies. There are two dimensions:
20+
21+
Specificity - how broadly the approval applies:
22+
23+
* Command prefix - approve any command that starts with a specific prefix.
24+
* Exact command - approve only the precise command line.
25+
* All commands - approve all terminal commands.
26+
27+
Scope - how long the approval lasts:
28+
29+
* This session - applies for the rest of the current conversation.
30+
* This workspace - persists for the project.
31+
* Always - applies across future sessions.
32+
33+
For example, if Python `uv` commands are trusted in a project, use an approval that covers `uv` in the workspace. If tighter control is needed, allow only the exact command in the current session.
34+
35+
![Expanded approvals menu showing approval specificity and scope options in VS Code chat.](../images/foundations/expanded-approvals.png)
36+
37+
You can also manage these rules in VS Code settings through **Configure Auto Approve**.
38+
39+
## Permission levels
40+
41+
Beyond individual approvals, the permissions picker in the chat input area controls how much overall autonomy the agent has for the session.
42+
43+
### Default approvals
44+
45+
The default mode. Copilot follows configured settings and shows confirmation dialogs where required. This is the right starting point when learning what the agent does or when working on something sensitive.
46+
47+
### Bypass approvals
48+
49+
Auto-approves all tool calls and automatically retries when it hits errors. You're stepping back from step-by-step oversight and letting everything run uninterrupted.
50+
51+
With Bypass Approvals, the agent still stops and waits if it has a blocking question that requires a decision. You've removed the security prompts, but you're still in the loop for judgment calls.
52+
53+
### Autopilot
54+
55+
Autopilot goes further than Bypass. It auto-approves tool calls, auto-retries on errors, and resolves blocking questions on its own until it decides the task is complete.
56+
57+
> [!NOTE]
58+
> The first time you enable Bypass approvals or Autopilot, VS Code shows a warning. Both modes skip manual confirmations for actions that can modify files and run commands.
59+
60+
![Screenshot showing the approval picker in VS Code chat with Default approvals, Bypass approvals, and Autopilot options.](../images/foundations/approval-picker.png)
61+
62+
## Tool calls
63+
64+
Every action the agent takes shows up in the chat panel as a tool call. A tool call is simply the agent using one of its available tools.
65+
66+
The agent decides which tools to use based on your prompt and gathered context. You can also reference tools explicitly in your prompt with `#`.
67+
68+
* `#fetch`, pull in a specific web page.
69+
* `#codebase`, search across your project.
70+
* `#file`, attach a specific file.
71+
72+
Type `#` in the chat input to see the full list of context sources and tools available in the current session.
73+
74+
## The context window
75+
76+
The model can only hold so much information in memory at one time. This limit is the context window, measured in tokens. When the context window fills up, the model starts losing track of earlier parts of the conversation.
77+
78+
Select the token usage indicator in the chat panel to see a live breakdown of how the budget is being used.
79+
80+
![Screenshot showing the context window indicator in VS Code chat with token usage and context breakdown details.](../images/foundations/context-window.png)
81+
82+
### What's in your context budget
83+
84+
The breakdown is split into two groups.
85+
86+
System (fixed overhead per request):
87+
88+
* System Instructions - built-in rules that shape how the agent behaves
89+
* Tool Definitions - descriptions of all available tools
90+
91+
User context (grows as you work):
92+
93+
* Messages - conversation history: your prompts and the agent's responses
94+
* Tool Results - output from tool calls, like terminal output and file reads
95+
96+
On short sessions, system overhead takes most of the budget. As sessions grow, tool results and messages start to dominate.
97+
98+
This is why being selective with tools and context matters. Everything you add contributes to the budget.
99+
100+
### Managing a full context window
101+
102+
When the context window fills up, VS Code automatically compacts the conversation by summarizing earlier messages. This lets you keep working without stopping the session.
103+
104+
You can also compact manually.
105+
106+
* Select **Compact Conversation** in the context window popup.
107+
* Type `/compact` in the chat input.
108+
* Add instructions such as `/compact focus on the encoder implementation decisions`.
109+
110+
If you want a full reset, start a new chat session.
111+
112+
Sub-agents also help here because they run isolated tasks in their own context windows. That topic is covered later in the series.
113+
114+
## What's next
115+
116+
You now understand how to stay in control while the agent works, using scoped approvals, choosing the right autonomy level, and keeping an eye on context budget. In the [next guide](reviewing-and-controlling-agent-changes.md), you will review the changes the agent made, accept or undo them at any granularity, and use checkpoints and forks to explore different directions without losing work.
117+
118+
## Learn more
119+
120+
* [Using agents in VS Code](https://code.visualstudio.com/docs/copilot/agents/overview)
121+
* [Chat overview in VS Code](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)
122+
* [Managing context for AI in VS Code](https://code.visualstudio.com/docs/copilot/chat/copilot-chat-context)
123+
* [Create and manage chat sessions](https://code.visualstudio.com/docs/copilot/chat/chat-sessions)

0 commit comments

Comments
 (0)
⚡