Prompt guidance
Prompting ACP is different from prompting a stateless chatbot. Agents can work inside projects, continue threads, inspect persistent computers, create tickets, review work, use files, and deploy resources. Strong prompts give the agent an operational goal, the project context it should use, and a clear definition of done.
Start from the operational goal
Lead with the outcome the agent should create. This helps the agent select the right tools, level of autonomy, and validation path.
| Lead with the deliverable | Start with the thing that should exist at the end: web app, report, database, function, presentation, migration, analysis, or fix. |
|---|---|
| Define observable done | Say what the agent should verify before stopping. Examples: app deployed, tests pass, report saved, screenshots attached, or review comments resolved. |
| Use operational verbs | Prefer build, deploy, audit, migrate, research, compare, summarize, update, refactor, validate, or monitor over vague instructions like help with. |
| Name the user outcome | Tell the agent who the work is for and what decision or workflow it should support, so it can choose the right level of detail. |
Use project context for real work
Projects give agents strategy, releases, tickets, comments, reviewers, files, and resources. Use them whenever the work should survive beyond one chat.
| Use projects for multi-step work | If the goal needs planning, tickets, resources, reviews, or several agents, ask mission control to turn the goal into a project plan first. |
|---|---|
| Reference releases and tickets | Tell the agent which release, ticket, or backlog area it should operate in. This keeps implementation work attached to the right project context. |
| Describe review expectations | State whether a ticket should go to review, who reviews it, and what evidence the reviewer should inspect before accepting or requesting changes. |
| Mention adjacent work | Call out previous tickets, next tickets, dependencies, blockers, and human-owned tasks so the agent can avoid duplicate or out-of-order work. |
Mission control
Use it when the goal needs strategy, releases, ticket cleanup, backlog planning, or a reset of what the project should do next.
Tickets
Use tickets when work has a clear owner, status, reviewer, subtasks, dependencies, and acceptance criteria.
Resources
Use resources when agents should deploy or manage web apps, functions, databases, auth, secrets, or runtimes as part of the project.
Reviews
Use reviews when the agent should not mark the ticket done until a human or reviewer agent has inspected the result.
Be explicit about state
ACP agents can continue from a real computer and thread history. Tell them whether to preserve, inspect, fork, or reset that state.
| Continue or start fresh | Say whether the agent should continue from the current thread and computer state, inspect an existing workspace, or create a new clean environment. |
|---|---|
| Inspect before editing | When state already exists, tell the agent to inspect files, deployments, logs, tickets, and resources before changing anything. |
| Keep scope visible | Name the computer, project, repository, resource, branch, or directory the agent should stay inside. |
| Choose the safety path | If the current state is fragile, ask the agent to fork, create a new branch, draft a plan, or ask for approval before destructive changes. |
Name artifacts and checks
Concrete outputs are easier to inspect, review, reuse, and continue. Name the artifact, where it should live, and how the agent should verify it.
| Files and reports | Name the expected files and formats: markdown report, spreadsheet, deck, JSON export, screenshots, diagrams, or a folder of generated assets. |
|---|---|
| Product resources | If the output should be live, say which resource to create or update: web app, function, database, auth module, secret vault, or agent runtime. |
| Acceptance checks | Ask the agent to validate the output with tests, smoke checks, screenshots, API calls, database reads, or deployment logs before it stops. |
| Handoff summary | Request a concise final summary with what changed, where to find it, how it was verified, and what remains blocked or risky. |
Set boundaries before tools run
Agents can browse, edit, deploy, and operate cloud resources. Good prompts make the allowed surface area visible before execution starts.
| Allowed tools | Say whether the agent may browse, install packages, call APIs, use skills, edit files, deploy resources, or create new computers. |
|---|---|
| Security boundaries | Identify secrets, private data, customer data, production resources, or compliance constraints that should not be exposed or modified casually. |
| Design and quality bar | Describe product design constraints, tone, accessibility expectations, browser support, performance targets, or documentation standards. |
| Budget and runtime | For large work, state whether the agent should optimize for speed, quality, cost, or an approval checkpoint before spending more time. |
Prompt for iterative execution
Large work should not be compressed into one giant instruction blob. Use planning, tickets, reviews, and follow-up runs to keep quality high.
| Plan first when ambiguous | Ask for a short plan before execution when the agent needs to choose architecture, resource boundaries, or a multi-ticket breakdown. |
|---|---|
| Let agents explore | Do not paste every detail into the prompt. Tell the agent where the context lives and what to inspect: project strategy, tasks, files, logs, or comments. |
| Use review loops | For important tickets, ask the implementation agent to move work into review and the reviewer to either accept or request specific changes. |
| Keep the next step clear | End prompts with the next concrete objective, especially when work should continue across several threads or agents. |
Prompt examples
Use these as starting points for common ACP workflows. Replace project names, tickets, resources, and acceptance checks with your own context.