imaga logo
Engraving of a belt conveyor that splits in two at a fixed wedge, on a beige background. On the incoming belt, sealed envelopes and bundles of banknotes lie mixed; past the wedge, one branch carries only envelopes and the other only banknote bundles.

The LLM Proposes, Code Executes: How to Separate Reasoning from Side Effects in a Production Pipeline

If your AI agent calls APIs and performs external actions, a routine retry after a timeout can create a duplicate or leave the system in an unknown state. Here's how to separate the model's decision from its execution, and when to retry a request, reconcile the result, or bring in a human.

A user asks an AI assistant to refund the payment for an order. The model parses the free text, finds the order, picks a reason, and calls the API. After 30 seconds, the orchestrator receives a timeout. What now: retry the request, ask for the operation's status, or hand the case to a human?

If all the logic sits in one prompt and one agent loop, you have to guess the answer together with the model. The first call may never have reached the API, may have succeeded without returning a response, or may have hung after a partial write. A blind retry can create a second refund. Declining to retry leaves the first request in an undefined state.

A double refund costs money and triggers a customer complaint. An unknown status sends every such case to manual review.

At Imaga, we build an LLM gateway and a prompt-injection detector. In the gateway, the model is one of the request scanners, next to regex and NER. The policy engine forms the verdict, and the key's enforcement mode decides whether to apply it. The model gets no say in that decision. We covered how the gateway hides sensitive fragments from the provider and puts them back into the response in our article on DLP for LLMs.

Any agent that writes to external systems needs the same principle: the model proposes, code executes. The model turns free text into a proposed action. Permissions, calculations, writes to an external system, and handling an unknown outcome stay with code.

This article shows how to build such a pipeline, from the choice between a workflow and an agent to the log and the checks before release. Separate sections cover when a human approves an action and what to do about a timeout. The goal is for the team to see, during an incident, what the model proposed, which rule the code applied, who allowed the action, and which effect the external service confirmed.

Should you build a workflow or an autonomous agent for tasks that change data in other systems?

The tempting simple move is to hand the whole process to one prompt and one agent loop. It saves the first lines of code but immediately mixes interpretation, permission checks, and the external effect. We find it more useful to drop the "workflow first, then agent" ladder and treat the two as separate branches of the architecture.

In Anthropic's engineering guide Building effective agents, a workflow is a path defined in advance by code, and an agent is a process in which the model chooses the steps and the tools. The authors recommend starting with the simplest sufficient solution and accounting for the latency and cost that agentic complexity brings. These are Anthropic's observations from working with dozens of teams that build agents.

Ask four questions before you choose:

  1. 1
    How ambiguous is the input? Free text needs interpretation; a limit check, a calculation, and a status transition usually have exact rules.
  2. 2
    Can you check the result formally? A JSON schema checks types and required fields. It cannot tell whether a compensation is appropriate.
  3. 3
    Is the route known in advance? If every request goes through classify → validate → approve → execute, the route already exists. If the number of steps depends on the data found, a bounded agent loop is acceptable.
  4. 4
    What does a wrong action cost? A draft can be deleted; a payment, a publication, an access change, or a CRM write leaves an external trace.

From these questions we get a working allocation:

Flowchart: "What is unknown? The shape of the task" leads to "Two factors: uncertainty + cost of an error" and then to "Choose the owner." Three dashed branches go to the LLM (language; dynamic choice), Code (rules; permissions; writes), and a Human (the criterion is incomplete); a branch labeled "limit" runs from the LLM to Code limits: budget + tools.

The shape of the uncertainty and the cost of an error decide who owns each step: we give language to the model, rules and permissions to code, and an incomplete criterion to a human. A budget and a set of tools limit what the model can choose.

TaskMain executorReason
Classify free textLLMThe class boundary depends on language and context
Calculate a price or a limitCodeThe formula is known and must be reproducible
Choose the next research stepAgent loop with limitsThe route depends on an intermediate result
Check permissionsCode, using trusted contextThe model must not assign itself authority
Approve a risky exceptionHumanThe formal criterion is incomplete and the cost of an error is high
Perform a writeCode through an explicit contractIt needs idempotency, audit, and handling of an unknown outcome

This allocation does not pick the architecture for you. It helps you name the source of uncertainty. If only the input text is ambiguous, an autonomous agent adds states to a route that is already known.

An agent loop needs budgets for steps, time, and tools. End every call with a machine-readable outcome: continue, complete, needs_input, blocked_by_policy, or failed.

The same principle of allocation works in our gateway. Its minimal route: request → scan of request slots with regex, NER, and a model → the policy engine forms the verdict → the key's enforcement mode decides whether to apply it → reversible tokenization of sensitive fragments → upstream → scan of the streamed response with holdback → rehydration → incident log.

We drew the component boundaries by verifiability. Regex handles personal data with a fixed format, NER handles names and organizations, and the model handles attack semantics. When spans overlap, regex takes priority. The model gets no say over permissions, quotas, calculations, idempotency, or the decision whether to apply a verdict; see the allocation above.

How do you validate what an LLM proposes before it writes to an external system?

Back to the refund: the model parsed the user's request, found the order, and picked a reason. A convenient boundary runs along the proposal object. The model turns context into a constrained structure, and that structure changes nothing yet:

from dataclasses import dataclass
from decimal import Decimal
from typing import Literal

@dataclass(frozen=True)
class RefundProposal:
    order_id: str
    reason: Literal["duplicate", "quality", "delivery", "other"]
    amount: Decimal
    confidence: float
    evidence_ids: tuple[str, ...]

After it receives a RefundProposal, the deterministic layer reloads the order and checks the amount, the status, and the caller's permissions. confidence helps with routing and does not override the business rule. You cannot take its threshold from documentation or set it by eye: calibrate the threshold on labeled data for the balance of precision and recall you need. evidence_ids point to records already available to the system; free text from the model cannot count as evidence.

A separate boundary is needed after the model responds. Structured output validates the shape, but a formally valid tool-call can still carry a dangerous argument. So before a side effect, code revalidates the schema and inspects the arguments as text; for irreversible actions, human approval comes on top.

You can build execution as a sequence of explicit gates:

def handle_refund(command, actor, store, payments):
    proposal = llm.propose_refund(command.text, command.context)

    validate_schema(proposal)
    order = store.get_order(proposal.order_id)
    validate_business_rules(proposal, order)
    require_permission(actor, "refund", order.account_id)

    if needs_human_approval(proposal, order):
        return queue_for_review(command.id, proposal)

    # Save operation_id before the first external call:
    # otherwise a restart between the API call and the write will sever the link to the operation.
    operation_id = stable_operation_id(command.id, "refund")
    store.save_operation_id(command.id, operation_id)
    return execute_with_reconciliation(
        operation_id=operation_id,
        request=build_refund_request(proposal, order),
        client=payments,
    )
Flowchart of an LLM proposal passing three gates in a column: schema, business rules, and permissions. A failure at any gate leads to a structured error with a code and a route. From permissions, a high-risk case goes to human review and, once approved, to the executor; an allowed case goes straight to the executor, then to the external API, a receipt with the confirmed outcome, and a write to state with the operation_id and status.

The model's proposal passes through the schema, the business rules, and the permissions; a refusal at any gate becomes a structured error with a code and a route, and a risky case goes to a human. operation_id is saved before the first call to the external API, and the confirmed outcome is written to state after the response.

The example pins down who owns each decision: the model owns the proposal; code owns the schema, the facts, the permissions, and the side effect; a human owns a class of exceptions named in advance. The example is not a ready-made library and does not guarantee safety on its own.

This is where the engineering payoff of the separation shows up: you can test the contract in parts. propose_refund needs a dataset and a semantic evaluation. validate_business_rules works with ordinary unit tests. execute_with_reconciliation needs integration tests with dropped connections and repeated event delivery. A single overall metric will not show where exactly the error occurred.

When should a human approve an AI agent's action?

The refund code above has a queue_for_review branch: some proposals go to a human, and the rest, once they pass the gates, go to execution.

Engraving of a round brass railway tablet with a square hole in the centre, on a beige background; raised letters around the rim read "MONTGOMERY" and "ABERMULE."

On January 26, 1921, a train left Abermule station in Wales with the wrong tablet: the token for the stretch of single track it had just come through. The inspector found the station names "clearly enough shown in raised lettering," but the staff handed the tablet over without reading it, and the crew didn't check it. The train met an express head-on, and 17 people died. An approval nobody reads fails the same way.

The blanket rule "AI needs double-checking" gives no reason to put a human in the loop. A meaningful trigger combines two conditions: the formal criterion is incomplete and a mistake is expensive. For a low-risk draft, manual approval of every step builds a queue with no noticeable benefit. Worse, the reviewer falls into approval fatigue: an approval that always ends in a click on "Yes" creates a false sense of control. For an irreversible operation, even high model confidence does not replace permissions and explicit approval. The higher the cost of an error, the closer the approval point should sit to the side effect and the further from the start of the pipeline.

Write into the contract exactly what the reviewer sees: the original request, the proposal, the confirmed facts, the rules that fired, and the expected side effect. An "Approve" button next to a polished explanation from the model masks the risk when the human cannot see verifiable grounds.

Is it safe to retry an API call after a timeout if it may have changed data?

The 30-second wait from the introduction says nothing about what had already happened on the API side. A "retry three times on error" rule suits some reads but is dangerous for writes. RFC 9110 allows a client to retry an idempotent request automatically if the connection fails before the client has read the server's response. A client should not automatically retry a request with a non-idempotent method unless it has a way to know that the request's semantics are actually idempotent, or a way to detect that the original request was never applied.

Engraving of a handwritten bill of exchange on a beige background, dated Virginia, September 1769, for £112 15s 9d: "At Sixty Days Sight of this my Second Bill of Exchange, my first & Third of same Tenour & Date not paid, pay to Messrs Jones & Clarke…", signed Carter Braxton and addressed to Messrs Cary & Company, merchants in London.

To pay across the ocean, an 18th-century merchant wrote a bill of exchange in two or three copies and sent them on different ships, since any ship could be lost. Each copy named the others. This one, drawn in Virginia in 1769 by Carter Braxton, later a signer of the Declaration of Independence, reads "my first & Third of same Tenour & Date not paid." Whichever copy reached London first was to be paid, and only once. That guarantee lived on the paying side: under Britain's Bills of Exchange Act of 1882, a payer who accepted two copies of one set could be held liable on both.

It is worth splitting a timeout into at least four outcomes:

  • the request was not sent: an ordinary retry is allowed;
  • the remote system returned a confirmed refusal: whether to retry depends on the class of error;
  • the request was sent but the response was lost: the outcome is unknown, so a read-back or reconciliation comes first;
  • a partial response has already gone to the consumer: do not retry automatically, even if you have an idempotency key.

The last case matters most for streaming. In our gateway, a provider could return HTTP 200, send the first bytes, and cut the stream a few seconds later. Before the first byte, we retry the request on the same model, then go through the fallback models in the registry. After the first byte, we do not retry: the client gets an explicit abort.

Decision tree for a timeout. If the request was not sent, a safe retry; after an explicit refusal, the retry policy decides by error class; if the response was lost, the outcome is unknown, so a read-back checks the effect and reconciliation compares expected with actual, ending in success, retry allowed when there is no effect, or manual review when nothing can be proved.

The failure phase decides what to do about a timeout. When the outcome is unknown, a read-back and reconciliation end in one of three results: success, retry allowed, or manual review.

An idempotency_key field helps only together with the receiving API's contract. You need to know how long the key is stored, its scope of uniqueness, what happens when the same key arrives with a different body, and the format of the response to a repeated request. The mere presence of the field does not create exactly-once semantics.

A minimal state machine for a write can look like this:

proposed
  ↓
validated
  ↓
executing
  ├─→ succeeded
  ├─→ failed_safe_to_retry ─→ retry_allowed
  └─→ outcome_unknown ─→ reconciling
        ├─→ succeeded
        ├─→ retry_allowed
        └─→ manual_review

In production, these must be real persisted states, from which operation_id, the attempt number, and the last confirmed transition are restored after a restart.

Temporal distinguishes timeouts for waiting to start, for execution, and for total time, and a heartbeat records a long-running Activity's progress for the next attempt. This is an example from one specific product. The portable conclusion: the failure phase and observable progress matter more than the word timeout.

What should you log in an LLM pipeline to debug an incident without the model itself?

A model can explain the same input in different ways; the operational log has to stay unambiguous. In practice, start with two separate fields: "what the model decided" and "what the system did." For us, this separation is what showed that in the first iteration of inline blocking, 90 of 99 blocks were false and hit the system prompts of coding agents: a single overall metric was not enough for diagnosis. In the gateway's log, "verdict" and "applied action" remain separate fields.

For each run, it helps to save:

  • run_id, operation_id, the parent request, and the attempt number;
  • versions of the prompt, the model, the tool schema, and the policy;
  • a hash or a safe copy of the proposal;
  • the result of each gate with a reason code;
  • state transitions, the tool request, and the confirmed response;
  • the final receipt, or an outcome_unknown status.

Never send raw user text, access tokens, or personal data to an observability system without thinking it through. In our case, the log contains the versions of the model, the adapter, the policy, and the rules; the verdict; the applied action; the reason code; the correlation id; and the latency of each stage. For text, we store a masked preview; the full text is kept behind a separate permission, encrypted and audited. Text reaches the SIEM only when the absence of personal data is confirmed; otherwise, the SIEM gets a list of the detected types.

The trace answers the on-call engineer's questions: which prompt version was used, why the gate let the action through, whether the request reached the external API, and whether the read-back matched the expected effect. If the answer has to be reconstructed from the model's reasoning, there is no reliable operational state.

How do you test and monitor an LLM pipeline before and after release?

Checking an LLM component before release and controlling a single dangerous action solve different problems. It helps to separate four control layers. This division is our own engineering framework; it does not appear in the official NIST taxonomy:

  1. 1
    Offline eval compares versions on a fixed set of attacks and benign controls, class by class: whether the verdict matches the expected one, whether the model populates the proposal, whether the new version degrades the rare classes. A catch rate measured only on requests that were already blocked is not enough for this.
  2. 2
    Release gate decides whether a specific combination of model, prompt, tools, and policy can ship. In our detector, a new version passes four checks: blind spots, precision on real correspondence, forgetting on paraphrases, and red team. The threshold and the list of mandatory tests are versioned together with the artifact.
  3. 3
    Runtime gate checks the current proposal, the permissions, the limits, and the state of the external system before the action.
  4. 4
    Monitoring looks for drift after release: growth in outcome_unknown, in the share of fail-open, in upstream 5xx, in the scan queue, in retries, in manual reviews, and in reconciliation mismatches. For our setup, the working targets are under 1% false blocks of business correspondence and no more than two minutes to an alert. These are SLOs for our setup; another setup has to set its own.

Like the confidence threshold, the detector's threshold is calibrated on labeled data. In our detector, calibration showed that a threshold of 0.2 gave a precision of 1.0, while 0.5 lost about half the recall. This is the result of one specific sample: on other data, you recalibrate the threshold.

Cycle of four control layers: offline eval leads before release to the release gate, at release to the runtime gate, and in production to monitoring. Drift and incidents go into the dataset and policy, which feed the next version back into offline eval.

The four layers run from version to operation; drift and incidents from monitoring feed the dataset and the policy of the next version, and the cycle starts again with offline eval.

NIST AI 600-1 (the Generative AI Profile) is a profile of AI RMF 1.0 for generative AI. The AI RMF has four functions: Govern, Map, Measure, and Manage. The profile covers both pre-deployment testing and post-deployment monitoring; post-deployment monitoring falls under Manage. The profile sets no numeric thresholds, but it advises an organization to define its own minimum thresholds for approving a release.

One of the failed iterations of our runtime gate was a tool-call inspector that blocked calls by tool name alone. On live traffic, it blocked the launch of a subagent and the deletion of a temporary file because the names looked dangerous. After the rollback, we kept unconditional blocking only for catastrophic arguments and made the name-based heuristic subject to the key's enforcement mode. In observe mode, it only records the event.

Where to start

We would skip a full rebuild and start with the part where an error already produces an expensive or hard-to-diagnose result. This way, a simple one-shot app gets controlled boundaries, one risk at a time.

  1. 1
    List all external writes, sends, and permission changes. Move them out of the model loop into separate functions.
  2. 2
    Introduce a typed proposal and forbid the model from passing arbitrary arguments to the executor.
  3. 3
    Add schema, business, and permission gates. For every refusal, define a reason code and the next route.
  4. 4
    Persist the state machine and a stable operation_id before the first call to the external API.
  5. 5
    Separate failed from outcome_unknown; implement read-back wherever the API lets you verify the effect.
  6. 6
    Build an offline eval for the probabilistic part and ordinary tests for the deterministic rules.
  7. 7
    After that, check whether a task remains where the next step cannot be defined in advance. Add a bounded agent loop only for that task.

The last step guards against false autonomy. If the model always calls the same three tools in the same order, you have a workflow with unnecessary nondeterminism. If the research path changes after every result, an agent can be justified, provided it has limits, observable state, and a safe boundary for side effects.

Before release, ask the team to answer seven questions:

  • Can the same request create two external effects?
  • What happens after a restart between the write and saving the response?
  • Which component checks permissions against trusted data?
  • How does the system tell a safe retry from an unknown outcome?
  • Which decisions require a human, and what data does the human see?
  • Can you reproduce an error without the model's reasoning?
  • What does the system do if the checking component is unavailable, fail-open or fail-closed, and who owns that decision?

Our policy is set by operation class: fail-closed for irreversible actions, fail-open for reads. The tradeoff between coverage and safety has to be written down in advance, so the on-call engineer does not have to invent it during an incident.

Engraving of the top of a snow-covered wooden railway signal post on a lime background: the signal arm, heavy with snow, hangs halfway down beside an empty slot in the post, and a lit lamp with a frame of glasses sits on a bracket to the right.

On January 21, 1876, in a blizzard, the signals at Abbots Ripton showed "clear" while a coal train was still on the main line ahead. The Flying Scotsman ran into it, and minutes later an express from the other direction hit the wreckage; 13 people died. Snow had stopped the signal arms short of danger, and at night "clear" was just a white light, which a lamp also showed when its red glass failed to move in front of it. Afterward, signals were built to rest at danger by default.

You can go wrong in either direction. If a human approves every action, the queue grows, the reviewer clicks "Yes" without reading, and control becomes a formality. If actions go through without checks, duplicate refunds and operations with an unknown status pile up in the log.

Back to the refund from the start of the article. If it is unclear after a timeout whether the request arrived, the system never retries blindly. It uses the saved operation_id to ask for the refund's status and compares it with the expected one. The refund went through: the operation is complete. No refund: a retry is allowed. The outcome cannot be proven: the case goes to a human.

If we were starting over, the first thing we would add is two fields, "what the model decided" and "what the system did," and a deterministic log of states with reason codes. The model may propose, code may act, and between them there has to be a log line that an engineer can understand a month later without the model itself.

If you're connecting an AI agent to payments, a CRM, or access rights and want every action it takes to be verifiable and open to investigation, talk to Imaga. We'll help you separate the model's decisions from execution and check the pipeline before launch.

Request a project estimate

Up to 3 files, 5 MB each.
Your privacy is protected — we'll use your details only to reply to your inquiry. See our Privacy Policy.
What happens next
1
NDA. If checked, we'll send a standard NDA for e-signature right away.
2
Discovery. We'll reach out to clarify goals, constraints, and discuss potential AI use cases if they make sense.
3
Proposal. You'll get timeline and budget, plus key architectural options and risks.
We build for