Agent tutorials and guides

Choose a tutorial to learn with a sample project, or follow a guide to apply an agent workflow to your own codebase in VS Code.

Choose where to start

If you're new to both VS Code and AI, first install the editor and open a workspace. If you already know VS Code, use one of these sample projects to learn the agent workflow:

Already use agents? Skip the sample projects and follow the experienced-agent fast track. If you want AI help without delegating changes, choose a lighter-weight AI feature.

Or jump to a task:

• Work on a project.
• Test and validate.
• Customize and coordinate agents.
• Improve results and recover.

Experienced-agent fast track

Use your own repository and keep the default harness and session settings for your first task. Adjust them only when your provider, environment, or project requires a different setup.

1. Open your repository as a workspace so that files, source control, terminals, tests, and agents share the same project context.

2. Map your existing workflow to VS Code sessions, then understand the session controls. If provider or local, remote, and cloud execution constraints matter, choose a session target.

3. Start with a bounded task in your own repository. Explore the codebase without making changes, or add a feature with your existing development environment and tests.

4. Review and validate the code edits before you integrate them.

After one real-project task, adapt agents to your project and compare quality, reliability, and AI credit usage. If you move between supported applications, learn how to view sessions from other applications.

On a managed device, your organization might control which agents and providers are available. Developers can review the agent availability troubleshooting steps, and administrators can manage AI settings. For keyboard, screen reader, and low-vision workflows, use the Accessible View and other accessibility features.

Work on a project

• Explore a codebase: trace a behavior without editing files and verify explanations against source references. Use your own repository.

• Add a feature: research, plan, implement, and verify a bounded change. Use your own repository with a working development environment and tests.

• Fix an API bug: reproduce a pagination bug, add a regression test, and review the fix. Sample project. Requires Node.js 22 or later and Git.

• Refactor safely: change code structure in reviewable steps while preserving behavior and checking existing callers. Use your own repository.

• Work with Jupyter notebooks: create or edit a notebook, run cells, and review analysis results. Use your own data. Requires the Jupyter extension and a notebook kernel.

Test and validate

• Add tests to existing code: generate tests for a function or module, run them, and review assertions, failures, and coverage. Use your own project.

• Validate a web app with browser tools: build a calculator app and check it against observable acceptance criteria. Sample web app.

• Set up test-driven development: create custom agents and instructions for a repeatable test-first workflow. Workflow setup, rather than a one-off testing task.

Customize and coordinate agents

• Adapt agents to your project: share project instructions with your team, then add skills or specialized agents where needed. Use your own repository.

• Set up a context engineering workflow: curate project context and connect planning to implementation with instructions, custom agents, and prompt files. Workflow setup.

• Run independent tasks in parallel: work in separate Git worktrees, review each result, then integrate and retest the changes. Use your own Git repository after completing a single agent task.

Improve results and recover

• Get an agent back on track: choose whether to steer a request, recover unwanted changes, or reset conversation context.

• Reduce AI credit usage: compare model costs and results, focus context, and scope tools to reduce unnecessary usage.

• Find prompt examples: adapt prompts for exploring code, building features, debugging, and testing.

Background and help

• How agents work: understand the agent loop and the role of models, context, and tools.

• Best practices for using AI: scope tasks, provide relevant context, and verify results.

• Troubleshoot AI features: diagnose setup, sign-in, connection, and other technical issues.