Agent

#Introduction

For decades the deal with a code editor was simple: it showed you text, and you did the thinking. You typed every character, you ran every command, you read every error message and decided what to do next. The editor was a very fast typewriter that happened to know about brackets.

That deal is changing.

Zed’s AI agent turns the editor into something that can act on its own: it reads your files, searches the project, writes code, runs terminal commands, looks at the output, and decides what to do next — all while you watch. You describe what you want; it figures out how and does it.

If that sounds a little unsettling, good. The first time a program edits your code by itself you should feel something. But the same thing happened the first time a calculator did your arithmetic, or the first time a compiler turned your text into a running program. The work didn’t disappear — it moved up a level. Your job stops being “type the characters” and becomes “decide what’s worth building and check that it’s right”.

This tutorial walks you from zero to a productive loop. We’ll open the panel, send a first message, learn how to feed the agent context, review what it changed, run several agents at once, and tidy up the settings so the whole thing fits the way you work. By the end you’ll treat the agent the way you treat a terminal: a tool you reach for without thinking.

Note

This page is about Zed’s agent — the thing that edits and runs code for you. Zed also has inline AI features (completions, inline transformations) that are configured separately. Don’t confuse “which agent runs my task” with “which model powers my autocomplete”: they’re independent choices.

Two official references are worth a bookmark before we start:

• Agents overview
• Agent Panel

We’ll cite them again at the end. Now let’s get our hands dirty.

#Before you begin

You need three things:

1. Zed itself. Download it from https://zed.dev. It runs on macOS and Linux. Keep it updated — the agent features move fast, and a tutorial written today assumes a recent build.
2. A project to work in. The agent is most useful inside a real codebase, where it can read your files and run your tools. Open any folder with Cmd + O (open folder). Even an empty folder works for the first experiments.
3. A way to talk to a model. This is the one step that needs a decision, so it gets its own section below.

Tip

If you’ve never opened a project in Zed, do it now. Almost everything the agent does — search, edit, run — happens relative to the open project. An agent with no project is like a chef with no kitchen: technically able, practically stuck.

#Giving the agent a brain

An agent is just a loop — read, think, act, repeat — but the thinking part is done by a large language model, and you have to tell Zed which one to use and how to reach it. You have a few options:

• Zed’s hosted models. The simplest path: sign in to Zed and use the models Zed provides. Tool calling works out of the box, so the agent can edit and run things with no extra setup.
• Your own provider key. If you have an API key from Anthropic, OpenAI, Google, or another provider, you can plug it in and Zed will talk to that provider directly. You pay them; Zed is just the client.
• A local model. Running something through Ollama or a compatible server? Zed can point at localhost and never send your code anywhere. Slower and usually weaker, but completely private.

We’ll cover switching models later. For now, open the agent settings and configure at least one, so the panel has something to talk to.

Caution

Not every model can drive an agent. Agentic work needs tool calling — the model has to be able to say “run this command”, “edit this file”. Older or smaller models often can’t, and the agent will sit there unable to act. Zed’s hosted models support tools out of the box; if you bring your own, check that it does too.

Task

Open Zed, open a real project folder, and configure one model in the agent settings. Don’t send a message yet — just confirm the panel opens without complaining that no model is set up.

Show solution

The status bar gets a ✨ icon once the panel is reachable. Click it; if Zed asks you to pick or configure a model, do that, and you’re ready. If it opens a chat box instead, you’re already configured.