netlify-agent-runner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Netlify Agent Runner

Netlify Agent 运行器

Run AI coding agents (Claude, Codex, Gemini) remotely on Netlify infrastructure to automate development tasks on your site.

在Netlify基础设施上远程运行AI编码Agent（Claude、Codex、Gemini），实现站点开发任务自动化。

Prerequisites

前置条件

The site must be linked to a Netlify project (via
```
netlify link
```
or
```
netlify init
```
).
Or skip linking entirely: pass
```
--project <name>
```
(a project ID or name) directly to
```
netlify agents:create
```
to target any Netlify site without linking first.
The Netlify CLI must be installed and authenticated
Agent runs consume plan credits. If the account has no available credits — or the agent/AI usage limit has been reached —
```
netlify agents:create
```
is blocked and the run won't start. That's an account/plan-state issue to surface to the user, not something to work around.

站点必须关联至Netlify项目（通过
```
netlify link
```
或
```
netlify init
```
命令）。
或完全跳过关联步骤： 直接在
```
netlify agents:create
```
命令中传入
```
--project <name>
```
（项目ID或名称），即可无需关联直接指定任意Netlify站点。
必须安装并认证Netlify CLI
Agent运行会消耗套餐额度。如果账户无可用额度——或已达到Agent/AI使用限制——
```
netlify agents:create
```
命令会被拦截，任务无法启动。这属于账户/套餐状态问题，需告知用户，无需自行解决。

Use only documented CLI surfaces

仅使用文档化的CLI接口

Interact with agent tasks only through the documented

netlify agents:*

commands (plus

netlify --help

and the public CLI reference). Do not go around the CLI:

Do not curl
https://api.netlify.com/...
to fetch, create, or stop a task — the endpoint shapes are not part of the public contract.
Do not run
netlify api <method>
as a recovery hatch when a documented command fails.
Do not read auth tokens out of
```
~/Library/Preferences/netlify/config.json
```
(or anywhere on disk) to authenticate side-channel calls.

If a documented command fails, report the exact error and context to the user and stop — don't invent an undocumented way to reach the task.

仅通过文档化的

netlify agents:*

命令（加上

netlify --help

和公开CLI参考文档）与Agent任务交互。请勿绕过CLI操作：

**请勿通过curl调用
```
https://api.netlify.com/...
```
**来获取、创建或停止任务——接口结构不属于公开约定内容。
**请勿在文档化命令失败时使用
```
netlify api <method>
```
**作为补救方案。
请勿从
~/Library/Preferences/netlify/config.json
（或磁盘任意位置）读取认证令牌来进行旁路调用认证。

若文档化命令执行失败，请向用户报告精确的错误信息和上下文后停止操作——请勿使用未文档化的方式执行任务。

How Agent Tasks Run

Agent任务运行机制

Read this before creating a task — agent tasks behave differently from running an agent locally, and the differences are easy to miss.

Remote, not local. Tasks run on Netlify infrastructure, not on your machine. They operate on the site's connected repository, not your local working tree. The remote agent only sees what has been pushed to the remote — it cannot see uncommitted or unpushed changes.
Branch-based. By default a task runs against the production branch (
```
main
```
or
```
master
```
). To choose a different base branch for the agent to start from, use
```
-b <branch>
```
and make sure that branch has been pushed to the remote first, or the agent will be working from code that doesn't exist remotely.
```
-b
```
sets the base (starting) branch — not where the results are written (see the next bullet).
Output lands on a new branch — not in place. The agent does not commit its changes onto the base branch you selected. It pushes its work to a new branch with its own Deploy Preview, so your existing branch (or
```
main
```
) is never overwritten. Review the task's results on that new branch / Deploy Preview — don't expect the base branch to change directly.
Asynchronous.
```
netlify agents:create
```
returns as soon as the task is queued — it does not block until the work is finished. When the command returns, the task is still running remotely.
No webhooks or callbacks. Nothing notifies you when a task changes state or completes. To find out what's happening, you have to poll with
```
netlify agents:show <task-id>
```
or
```
netlify agents:list
```
.
Statuses are terminal or not. A task moves through
```
new
```
→
```
running
```
→ one of
```
done
```
,
```
error
```
, or
```
cancelled
```
. Keep polling until the status is one of those last three before you act on the results.

创建任务前请阅读以下内容——Agent任务的运行方式与本地运行Agent不同，这些差异容易被忽略。

远程运行，非本地。 任务运行在Netlify基础设施上，而非你的本地机器。任务操作对象是站点的关联远程仓库，而非本地工作目录。远程Agent仅能看到已推送至远程仓库的内容——无法看到未提交或未推送的变更。
基于分支。 默认情况下，任务针对生产分支（
```
main
```
或
```
master
```
）运行。若要选择其他基础分支供Agent启动，使用
```
-b <branch>
```
参数，并确保该分支已推送至远程仓库，否则Agent将基于不存在的远程代码工作。
```
-b
```
参数设置的是基础（启动）分支——而非结果写入的分支（见下一点）。
输出结果存入新分支，而非原地修改。 Agent不会将变更提交至你选择的基础分支。它会将工作成果推送至新分支并生成对应的预览部署，因此你的现有分支（或
```
main
```
分支）永远不会被覆盖。请在新分支/预览部署上查看任务结果——不要期望基础分支直接发生变化。
异步执行。
```
netlify agents:create
```
命令在任务进入队列后立即返回——不会等待任务完成。命令返回时，任务仍在远程运行。
无Webhook或回调。 任务状态变更或完成时不会发送任何通知。若要了解任务进展，必须通过
```
netlify agents:show <task-id>
```
或
```
netlify agents:list
```
命令轮询。
状态分为终端状态和非终端状态。 任务会经历
```
new
```
→
```
running
```
→
```
done
```
、
```
error
```
或
```
cancelled
```
中的一种状态。请持续轮询直到状态变为最后三种之一，再根据结果采取行动。

Typical workflow

典型工作流

Create a task:
```
netlify agents:create "<prompt>" -a <agent>
```
. Note the task ID it returns (use
```
--json
```
to capture it reliably).
Poll for status:
```
netlify agents:show <task-id>
```
. Repeat periodically — there is no completion notification — until the status is
```
done
```
,
```
error
```
, or
```
cancelled
```
.
Review the results once the task reaches
```
done
```
(or inspect the failure on
```
error
```
).

创建任务：
```
netlify agents:create "<prompt>" -a <agent>
```
。记录返回的任务ID（使用
```
--json
```
参数可可靠捕获该ID）。
轮询状态：
```
netlify agents:show <task-id>
```
。定期重复执行该命令——无完成通知——直到状态变为
```
done
```
、
```
error
```
或
```
cancelled
```
。
查看结果：当任务状态变为
```
done
```
时查看结果（或在
```
error
```
状态下检查失败原因）。

Creating Agent Tasks

创建Agent任务

bash

undefined

bash

undefined

Run a prompt with the default agent

使用默认Agent运行提示任务

netlify agents:create "Add a contact form"

Choose a specific agent: claude, codex, or gemini

选择特定Agent：claude、codex或gemini

netlify agents:create --prompt "Add dark mode" --agent claude netlify agents:create -p "Update the README" -a codex netlify agents:create -p "Write unit tests" -a gemini

Target a specific branch

指定目标分支

netlify agents:create -p "Fix the login bug" -a claude -b feature-branch

Specify a project by name (if not in a linked directory)

指定项目名称（若不在关联目录中）

netlify agents:create "Add tests" --project my-site-name

Output result as JSON

以JSON格式输出结果

netlify agents:create "Add a footer" --json

undefined

netlify agents:create "Add a footer" --json

undefined

Options

参数选项

Flag	Description
`-a, --agent <agent>`	Agent type: `claude` , `codex` , or `gemini`
`-p, --prompt <prompt>`	The prompt for the agent to execute
`-b, --branch <branch>`	Git branch to work on
`-m, --model <model>`	Model to use for the agent
`--project <project>`	Project ID or name
`--json`	Output result as JSON

标志	描述
`-a, --agent <agent>`	Agent类型： `claude` 、 `codex` 或 `gemini`
`-p, --prompt <prompt>`	Agent需要执行的提示内容
`-b, --branch <branch>`	要操作的Git分支
`-m, --model <model>`	Agent使用的模型
`--project <project>`	项目ID或名称
`--json`	以JSON格式输出结果

Managing Agent Tasks

管理Agent任务

All

netlify agents:*

commands are project-scoped — they operate on a single project (the one your directory is linked to, or the one named with

--project <name>

), not on your whole team.

netlify agents:list

shows the tasks for that one project only; there is no team-wide command that lists tasks across all your sites. To see a different site's tasks, run from its linked directory or pass

--project <name>

for it.

所有

netlify agents:*

命令均为项目范围——仅操作单个项目（当前目录关联的项目，或通过

--project <name>

指定的项目），而非整个团队。

netlify agents:list

仅显示该项目的任务；暂无跨所有站点列出团队任务的命令。若要查看其他站点的任务，请在其关联目录中运行命令，或通过

--project <name>

参数指定该站点。

List tasks

列出任务

bash

undefined

bash

undefined

List all tasks for the current site

列出当前站点的所有任务

netlify agents:list

Filter by status

按状态筛选

netlify agents:list --status running netlify agents:list --status done netlify agents:list --status error

Output as JSON

以JSON格式输出

netlify agents:list --json


Status values: `new`, `running`, `done`, `error`, `cancelled`.

netlify agents:list --json


状态值：`new`、`running`、`done`、`error`、`cancelled`。

Show task details

查看任务详情

bash

netlify agents:show <task-id>
netlify agents:show <task-id> --json

bash

netlify agents:show <task-id>
netlify agents:show <task-id> --json

Stop a running task

停止运行中的任务

bash

netlify agents:stop <task-id>

bash

netlify agents:stop <task-id>

Use Cases

使用场景

Some of the many things you can do with Agent Runners:

Category	Example prompt
Prototyping / internal tools	"Build an internal dashboard for our HR team"
Code reviews	"Audit the code with fresh eyes and identify areas for improvement"
Security audits	"Do a deep security audit of our codebase to identify any potential issues"
Feature suggestions	"Based on our current codebase & docs, what should we build next?"
Performance improvements	"Scan our codebase for performance bottlenecks and suggest improvements"
Telemetry & analytics	"What analytics things are we not tracking but probably should"
SEO audit	"Audit our site for SEO issues — missing meta tags, broken links, slow pages, missing alt text"
Copy improvements	"Rewrite our landing page copy to be more compelling and conversion-focused"
Accessibility	"Run an accessibility audit and fix all WCAG 2.1 AA violations"
Mobile responsiveness	"Improve the mobile responsiveness — audit every page on small viewports"
End-to-end tests	"Add end-to-end tests for our critical user flows using Playwright"
Unit tests	"Generate unit tests for our untested utility functions"
Documentation	"Generate a README and contributing guide based on our codebase"
Error handling	"Add proper error boundaries, logging, and user-friendly error states throughout the app"
UX polish	"Add loading states, skeleton screens, & transitions to improve perceived performance"
Form hardening	"Add form validation, rate limiting, and spam protection to our contact form"
Edge Functions	"Add an edge function for A/B testing on our landing page"

Agent运行器可实现多种功能：

分类	示例提示
原型开发/内部工具	"Build an internal dashboard for our HR team"
代码审查	"Audit the code with fresh eyes and identify areas for improvement"
安全审计	"Do a deep security audit of our codebase to identify any potential issues"
功能建议	"Based on our current codebase & docs, what should we build next?"
性能优化	"Scan our codebase for performance bottlenecks and suggest improvements"
遥测与分析	"What analytics things are we not tracking but probably should"
SEO审计	"Audit our site for SEO issues — missing meta tags, broken links, slow pages, missing alt text"
文案优化	"Rewrite our landing page copy to be more compelling and conversion-focused"
无障碍优化	"Run an accessibility audit and fix all WCAG 2.1 AA violations"
移动端响应性优化	"Improve the mobile responsiveness — audit every page on small viewports"
端到端测试	"Add end-to-end tests for our critical user flows using Playwright"
单元测试	"Generate unit tests for our untested utility functions"
文档生成	"Generate a README and contributing guide based on our codebase"
错误处理优化	"Add proper error boundaries, logging, and user-friendly error states throughout the app"
UX优化	"Add loading states, skeleton screens, & transitions to improve perceived performance"
表单加固	"Add form validation, rate limiting, and spam protection to our contact form"
Edge Functions	"Add an edge function for A/B testing on our landing page"

Using as an Agent

作为Agent使用

If you are an AI agent, you can use

netlify agents:create

to delegate work to an agent running remotely on Netlify — for example, to get a second opinion from a different model.

IMPORTANT — ask for permission first, as a distinct confirmation step. Agent tasks run on Netlify infrastructure and cost the user credits, so a real approval gate matters. Get explicit permission before running any

netlify agents:create

command — and treat that as its own turn, separate from the user's original request. A directive-sounding prompt ("start a task…", "use the claude agent and pin it to Opus") is not itself the approval: it tells you what they want, but the billable command still waits for a yes.

Make the permission request a concrete proposal, not a menu:

The exact command, filled in — e.g.
```
netlify agents:create -p "<the real prompt>" -a codex
```
— not a
```
<placeholder>
```
and not a pick-one list of agents.
One agent, already chosen — commit to a single
```
-a
```
value and say why you picked it ("codex for a second opinion on the auth logic"), rather than offering claude/codex/gemini as interchangeable options.
Why, plus what happens after "yes": the run is asynchronous —
```
agents:create
```
returns as soon as the task is queued, there's no callback, and you'll poll
```
netlify agents:show <task-id>
```
for the outcome.
Even if a prerequisite is missing (not authenticated, not linked to a site, not a git repo yet), still show the exact command and chosen agent you'll run once it's resolved — surface the blocker and the concrete proposal, rather than collapsing to only describing the blocker.

Never run these commands without the user's approval.

Before delegating, understand what you're handing off (see How Agent Tasks Run above):

It runs remotely against the pushed branch — not your local work. The remote agent only sees code that has been committed and pushed. Do not delegate work that depends on your local, in-progress changes; the remote agent can't see them and will work from stale code. If a task needs your current changes, commit and push them first (or finish the work yourself).
It's asynchronous — delegating does not block you. The task runs remotely while you keep working. But because there are no callbacks, you have to poll (
```
netlify agents:show <task-id>
```
) to learn the outcome. Don't assume the task is done just because you delegated it — check the status before relying on or describing its results.
It's a separate, self-contained task — not a continuation of your session. The remote agent starts fresh from the repo and the prompt you give it. It has none of your conversation context, so write a complete, standalone prompt.

Useful for:

Cross-validation — get a second opinion on your implementation from a different model
Edge case discovery — another model may catch issues you missed
Alternative approaches — see how a different model would solve the same problem
Parallel work — kick off an independent task remotely while you continue on other work, then poll for its result

如果你是AI Agent，可以使用

netlify agents:create

命令将工作委托给在Netlify远程运行的Agent——例如，获取其他模型的第二意见。

重要提示——需先获取用户许可，作为独立的确认步骤。 Agent任务运行在Netlify基础设施上，会消耗用户的额度，因此必须获得明确的许可。在运行任何

netlify agents:create

命令前，请先获得用户的明确批准——并将该许可请求作为独立步骤，与用户的原始请求分开处理。即使用户给出指令性的提示（如"启动任务…"、"使用claude agent并指定Opus模型"），这不代表已获得许可：这仅说明用户的需求，但涉及计费的命令仍需等待用户明确回复"同意"。

许可请求应是具体的提案，而非选项菜单：

明确的命令，填写完整参数——例如
```
netlify agents:create -p "<真实提示内容>" -a codex
```
——不要使用占位符，也不要列出多个Agent供选择。
选定单个Agent——确定一个
```
-a
```
参数值并说明选择理由（如"使用codex对认证逻辑提供第二意见"），而非将claude/codex/gemini作为可互换选项提供。
说明原因及"同意"后的流程：任务为异步执行——
```
agents:create
```
命令在任务进入队列后立即返回，无回调，需通过
```
netlify agents:show <task-id>
```
轮询获取结果。
即使存在前置条件缺失（未认证、未关联站点、尚未创建Git仓库等），仍需展示一旦问题解决后将运行的明确命令和选定的Agent——同时告知用户当前的障碍和具体提案，而非仅描述障碍。

未经用户许可，切勿运行这些命令。

委托任务前，请了解任务的运行机制（见上方Agent任务运行机制）：

任务基于已推送分支远程运行，而非本地工作内容。 远程Agent仅能看到已提交并推送的代码。请勿委托依赖本地未完成变更的任务——远程Agent无法看到这些变更，会基于过时代码工作。若任务需要当前本地变更，请先提交并推送（或自行完成该工作）。
任务为异步执行——委托任务不会阻塞你的工作。 任务在远程运行时，你可继续处理其他工作。但由于无回调机制，必须通过
```
netlify agents:show <task-id>
```
轮询获取结果。不要假设委托任务已完成——在依赖或描述其结果前，请先检查状态。
任务为独立的自包含任务，而非当前会话的延续。 远程Agent从仓库和你提供的提示重新开始执行，无任何对话上下文，因此请编写完整、独立的提示内容。

适用场景：

交叉验证——获取其他模型对你的实现方案的第二意见
边缘案例发现——其他模型可能发现你遗漏的问题
替代方案探索——查看不同模型如何解决同一问题
并行工作——远程启动独立任务，同时你继续处理其他工作，之后轮询获取结果