what should deployment infrastructure return to a software agent?

An agent cannot operate infrastructure through vibes.

A green badge, a spinner, and a page of interleaved logs may be enough for a human who knows the system and can click around until the missing context appears. An agent needs stable state it can read, compare, and use to choose the next action.

This is what makes infrastructure agent-native. It is not a chatbot attached to a deployment dashboard. It is a machine contract around real operations.

the dashboard is a projection, not the contract

Dashboards are good at compression. They show a person the latest deploy, a status color, a URL, and a recent log tail. The person supplies missing context from memory.

Agents do not share that memory reliably. They may resume after context compaction, operate several environments in parallel, or receive a result from a subtask that did not observe the original deploy.

If the only interface says “latest deploy failed,” the agent still has to guess:

• latest for which environment;
• triggered by which commit;
• failed in which service;
• before or after a migration;
• whether a newer deploy superseded it;
• whether retrying would repeat a side effect;
• whether any shared resource was modified.

The machine contract should be authoritative beneath every presentation surface. The CLI, API, dashboard, PR comment, and email can render it differently, but they should not invent different answers.

1. stable identity

Every response should identify the thing it describes without relying on a mutable name such as “latest.”

For a deployment, that usually means:

• application and organization identity;
• environment kind and environment identifier;
• preview slug or branch identity when applicable;
• deploy identifier;
• source repository, commit, and branch;
• service identifier and role;
• managed-resource identifiers owned by the environment.

Identity needs scope. An app name may be unique only inside an organization. A service name may be unique only inside an application. A pull-request number is unique only inside one repository. Agents need the full join key, not the convenient fragment a dashboard happens to display.

The same principle appears in observability standards. OpenTelemetry distinguishes a logical service from a particular service instance and requires the instance identifier to be unique within its service namespace and name. That distinction lets telemetry remain attributable when several instances exist at once.

Without stable identity, parallel agent work eventually reads or mutates the wrong environment.

2. explicit state with terminal meaning

Infrastructure operations are state machines. Their interfaces should admit it.

Useful states distinguish:

• accepted but not started;
• building;
• deploying;
• awaiting a human decision;
• live or otherwise successful;
• failed;
• superseded by newer work;
• cancelled or expired.

An agent must know which states are terminal. “Waiting” can mean healthy queueing, a human gate, a stuck worker, or an unbounded poll. Each requires a different response.

State transitions should also be monotonic where the contract promises finality. A deploy marked superseded should not later become live because a delayed worker completed. A human approval request attached to a dead deploy should not remain actionable. A retry should create a new attempt or clearly resume the same one, never blur the two.

This gives the agent a bounded wait: poll until a documented terminal or paused state, honor the timeout, then return the exact outcome.

3. evidence scoped to the failed stage

“Deploy failed” is not a diagnostic.

A useful failure response names the stage, service, and evidence source:

• configuration could not be parsed;
• managed-resource isolation could not be provisioned;
• image build failed for the worker;
• migration job exited non-zero;
• API revision never became healthy;
• route publication failed after deployment;
• approval is required before a data-loss operation.

Logs should remain available, but an agent should not have to parse an unbounded stream to discover the failure class. Return a stable diagnostic code, concise explanation, relevant identifiers, evidence link or log cursor, retryability, and one grounded next action.

Structured output matters here. The Model Context Protocol allows tools to declare an output schema and requires results to conform when one is provided. The specification explains that schemas help clients and models understand and validate structured tool results. Deployment interfaces benefit from the same discipline even when they are plain CLIs or APIs.

The human-readable message and machine-readable fields should agree. JSON is not agent-native if the actual cause remains embedded in one prose string.

4. provenance across the whole change

Agents need to connect intent to observed runtime.

The minimum chain is:

repository state → preflight plan → deploy → service revisions → routes → managed resources → verification result

If any link is missing, the agent may test the wrong thing. A preview URL without a commit is ambiguous. A database branch without an environment owner is dangerous to reset. A log line without a deploy and service cannot prove which proposed change produced it.

Provenance should survive cleanup. After a preview expires, the audit record can retain identifiers and terminal outcome without retaining credentials or live resources. A later incident should still be able to answer which commit, plan, and human decision produced a production transition.

This is the machine side of the chain of custody described in the shared-staging problem. Isolation creates ownership. Provenance makes that ownership inspectable.

5. bounded recovery

An agent will retry. The platform needs to make retries safe enough to reason about.

Each operation should answer:

• Is this request idempotent?
• If it already succeeded, what identifier retrieves the result?
• If it failed halfway, which side effects survived?
• Can it be resumed, or must a new attempt start?
• What exactly will reset or delete target?
• Does rollback move traffic, restore state, or compensate an external action?

These are different recovery contracts.

A traffic rollback can route requests to an earlier image. It does not undo a database migration. Preview teardown can remove environment-owned resources. It does not reverse an email already sent through a third party. Reset can recreate one preview database branch. It must not infer a target from a mutable “current environment” selection.

Agents should receive dry-run or plan output before high-impact work, then the actual operation should bind to the reviewed target and plan. A broad “retry deploy” command that silently chooses the newest state is convenient until several changes are in flight.

6. authority as machine-readable state

Human review is not an error condition. It is a valid paused state in the deployment contract.

When a plan crosses launch, access, spend, or data-risk boundaries, the response should say:

• which operation is gated;
• why it is consequential;
• which target and plan were evaluated;
• who may approve it;
• whether self-approval is prohibited;
• when the request expires;
• what happens after approval, rejection, correction, or timeout.

The agent should be able to continue doing work below the gate while recognizing that it cannot perform the gated transition. It must not be handed a generic admin token and instructed to behave.

The human approval boundary should therefore be part of the platform state machine. Approval grants authority for the exact plan. A plan change invalidates the decision. A corrected push supersedes the old request.

output should lead to one next action

Agent-facing errors often fail in opposite directions.

One returns only 500 internal server error. The other returns a page of platform implementation detail with five speculative suggestions.

A better response is narrow:

1. state what failed;
2. name the affected object;
3. provide the relevant evidence;
4. classify whether retry is safe;
5. give the next action supported by the observed failure.

For example:

{
  "status": "failed",
  "stage": "preview_resource_provisioning",
  "code": "PREVIEW_ISOLATION_UNAVAILABLE",
  "deploy_id": "dep_...",
  "environment": { "kind": "preview", "slug": "queue-retry-a13f2" },
  "resource": { "type": "postgres", "name": "default" },
  "retryable": true,
  "dev_prod_untouched": true,
  "next_action": "repair the managed Postgres attachment, then retry this branch"
}

The exact field names vary by platform. The shape illustrates the contract: identity, state, cause, scope, safety, and next action arrive together.

Do not return a next action the platform has not proved. A health-check timeout can suggest inspecting startup logs. It cannot confidently tell the agent to increase memory unless evidence points there.

an evaluation checklist

Give the platform one multi-service change and force several outcomes: success, build failure, migration failure, health failure, approval pause, retry, supersession, rollback, and preview cleanup.

For each outcome, ask:

1. Can the agent identify the exact app, environment, deploy, commit, and service?
2. Is the state explicit, and does the agent know whether it is terminal?
3. Does the response name the failed stage and provide scoped evidence?
4. Can the agent retrieve logs without scraping a browser or mixing services?
5. Are output fields stable enough to validate against a schema?
6. Can the agent distinguish safe retry, resume, reset, rollback, and compensation?
7. Does provenance connect the runtime result to the proposed repository state?
8. Can the agent prove which preview resources it owns?
9. Does cleanup report partial failures instead of deleting the ownership record first?
10. Can a human gate pause the action without giving the agent a bypass?

Run the evaluation with two branches at once. Interfaces that rely on “latest” or implicit current context usually fail there first.

where floo fits

floo treats the CLI and API as operating surfaces for agents, not wrappers around dashboard clicks. Non-streaming CLI commands support structured JSON. Deploy and preview responses carry stable application, environment, source, deploy, URL, expiry, and managed-resource identity.

Preview commands remain scoped to the resolved preview. A branch, preview URL, pull-request reference, or exact slug must resolve unambiguously. Ambiguity fails closed rather than selecting a convenient match. Preview-managed resource output includes a dev_prod_untouched assertion and never returns plaintext credentials.

Deploy diagnostics classify configuration, build, migration, startup, and routing failures into structured surfaces. Logs can be scoped to the service and deploy the agent is investigating. Preview reset and teardown use the environment's managed-resource ledger, so the target is the resource owned by that preview rather than a name inferred from shared application state.

Human approval is part of the same state model. A high-impact deploy can pause awaiting approval before cloud work begins. The agent can inspect the request, but API-key authentication cannot approve it. Plan drift, rejection, supersession, and expiry have explicit outcomes.

This does not make the platform responsible for product correctness. The agent still needs to define and run the checks that matter to the application. floo's job is to return a running system and enough structured truth for the agent to observe it, repair it, and know when judgment belongs to a human.

Agent-native infrastructure is not infrastructure that accepts natural language. It is infrastructure that remains legible when the operator is a machine, several changes are in flight, failures occur halfway through, and authority must stop at a real boundary.