Picture a CI job waiting on an interactive coding agent. The process streams reassuring prose, asks a question nobody can answer, edits a few files, and eventually prints that the task is complete. It exits with code 0.
The pull request still cannot safely move forward. The machine does not know whether the agent changed the intended files, ran the required checks, skipped a step, or quietly gave up after producing a plausible explanation.
A terminal can be an excellent surface for a developer and a terrible contract for automation. Humans can interpret a conversation, clarify a request, and notice when the agent has wandered. CI needs explicit state and artifacts.
Keep the CLI for operators. Put a small task, session, and result boundary between that CLI and the rest of the delivery system.
One agent has two very different consumers
Coding tools now show up as editor assistants, terminal agents, browser builders, pull-request bots, and API-driven services. That variety is useful because the workflows are different. An engineer exploring a codebase needs a different interaction from a CI job reviewing every new pull request.
The mistake is making every downstream system learn the conversational habits of whichever agent happens to be installed today.
| An operator can... | Automation needs... |
|---|---|
| read streaming prose | structured status |
| answer a follow-up question | an explicit approval state |
| decide that a partial result is useful | named acceptance checks |
| interrupt when the task drifts | cancellation and timeout semantics |
| inspect the working tree afterward | a declared result artifact |
Terminal formatting changes. Prompts change. Agent versions add new questions and new modes. If a pipeline depends on matching those details, the pipeline is coupled to an interface designed for a person.
That coupling is usually invisible until the first unattended run hangs on a prompt or reports success without producing the artifact the next step expected.
Put a small session boundary above the process
AgentAPI is one concrete version of this architectural move: it places an HTTP control layer in front of several coding-agent CLIs and documents use cases such as pull-request review and MCP integration. The project makes the integration seam concrete without proving that every agent behaves identically.
An automation boundary can stay small. It needs enough structure to answer questions such as:
- What task did the caller submit?
- Which session owns the work?
- Is the run queued, active, waiting for approval, complete, failed, timed out, or canceled?
- What may the caller retrieve when the run ends?
HTTP may fit a service. A local supervisor could expose the same contract through files, a socket, or a job queue. Either implementation can give machines structured state instead of terminal prose.
Here is an illustrative task request, not a proposed standard:
repository: payments-service
goal: add validation for expired checkout sessions
constraints:
writable_paths:
- src/checkout/**
- tests/checkout/**
network: disabled
acceptance:
- npm test -- checkout
- npm run lint
outputs:
- patch
- check-results
- review-summary
The adapter translates that request into whatever the selected agent understands. It also translates process behavior back into session state. The workflow above the adapter should not need to know whether an agent prints a spinner, opens a full-screen terminal interface, or phrases a permission request differently after an update.
A structured boundary cannot make the output correct. It can make the run observable enough for another system to decide what happens next.
Version the work definition beside the code
Private prompt recipes are a bad foundation for team automation. Nobody can review when the recipe changed, which repository assumptions it contains, or why one engineer gets a different result from another.
Auggie combines an interactive terminal agent with codebase-aware custom commands and GitHub Actions workflows. That arrangement keeps repeatable work definitions in team-owned, versioned project context.
A repository task might define:
- the files an agent may inspect or modify
- required checks and their timeout
- commands that always need approval
- the artifacts a review job must return
- the conditions that turn a partial run into a failure
Reviewing those rules does not guarantee good agent output. It does something more basic: it makes changes to the automation visible. A pull request can show that a team widened a writable path, removed a check, or changed the expected artifact before that decision reaches every future run.
The agent still gets room to reason inside the task. The delivery system keeps ownership of the boundary around it.
A successful process exit is not acceptance
Agent automation often collapses three different events into one:
- the agent process stopped
- the agent claimed it finished
- the requested work passed its acceptance checks
Only the third event should unlock the next delivery step.
Intent is positioned around a lifecycle that starts with a feature description and continues through isolated work, verification, and delivery. That is a product-authored description, not independent proof of the workflow. It still points at the right integration question: what evidence crosses the boundary when the work is done?
For a coding task, a result contract may require:
- a patch or commit containing changes within the allowed scope
- the exit status and output of named checks
- a short summary of changed and intentionally untouched areas
- a machine-readable failure reason when an expected artifact is missing
Logs help with diagnosis, but dumping a transcript is not a result contract. The downstream reviewer should not have to replay a conversation to discover whether tests ran. Give it the diff, the checks, and the bounded summary directly.
Partial work needs the same precision. If the agent changed the code but a required test timed out, preserve the patch and return a failed acceptance state. The reviewer keeps the useful artifact without receiving a false success signal.
Normalize less than you want to
Once a team has two agents behind one boundary, the temptation is to design a universal agent protocol. That abstraction gets expensive quickly.
Agents differ in context handling, review modes, tool controls, permission models, and repository awareness. Flatten all of that into a lowest common denominator and the wrapper can erase the feature that justified choosing a particular agent.
Normalize the boring parts:
- task input
- session identity and lifecycle
- execution scope
- cancellation and failure
- required result artifacts
Keep native capabilities behind deliberate, named extensions. A workflow that opts into an agent-specific review mode should say so. Portability is useful only when the contract tells the truth about what is portable.
Direct CLI use also remains the right choice for interactive local work, experiments, and one-off tasks led by an operator. There is no need to turn every terminal session into a service. The boundary becomes necessary when another machine depends on the outcome.
The five-part contract
Before wiring an agent into CI or an internal tool, define five things.
1. Task contract
Name the repository, goal, constraints, and acceptance checks. Avoid hiding durable requirements in prompt prose that only one caller knows.
2. Session contract
Represent start, progress, approval, cancellation, timeout, and failure as explicit states. Do not infer them from terminal output.
3. Execution contract
Declare the workspace, writable files, available tools, network access, and approval boundaries. An API wrapper cannot compensate for an undefined authority model.
4. Result contract
Require the diff, test result, log, summary, or other artifact that lets the next system evaluate the run. Process completion and task acceptance are separate facts.
5. Capability escape hatch
Allow a workflow to request a native feature on purpose. Mark that dependency instead of pretending the workflow will behave the same on every agent.
These five parts are a practical review checklist, not an industry standard. A small team may implement them with a local supervisor and a result directory. A platform team may use an API, job queue, and artifact store. Both implementations can enforce the same narrow contract.
Make the run reviewable first
Before adding a coding agent to an automated delivery path, the team should be able to answer five questions:
- What exactly starts the task?
- How does the caller observe, cancel, or time out the session?
- Which resources and permissions bound the run?
- Which artifacts and checks prove acceptance?
- Which parts depend on a native agent capability?
If the answers live only in a prompt and a terminal transcript, the system is automating a conversation rather than relying on an API.
An honest boundary may also make the agent easier to replace. More immediately, it lets reviewers judge the work without having to trust the agent's final sentence.
Top comments (0)