AI-native Architect: agents under control, tools, and a verifiable control plane

An operator asks the system to reprocess an ambiguous invoice "until it looks right." The agent calls the extractor, looks at the result, doesn't like the empty amount, calls again with a slightly different prompt, looks again, calls a third time. Each call spends budget. None of them proves the fourth result is more correct than the first - only that the system tried harder. If nothing outside the model says when to stop, how many tools it may call, or who has to approve the final output, "trying harder" and "getting better" collapse into the same thing from the system's point of view. This incident is synthetic. It does not describe a customer, a support ticket, or a production run.

Chapter 2 answered a question that comes before any agent: who owns which document, and does that decision survive a document_id that collides across tenants. This chapter takes that contract as given and asks the next one: now that ownership is settled, when is it worth letting a model choose dynamically which tool to call, and what stops that choice from becoming a cost, security, or quality incident? The thesis is operational, not philosophical: useful autonomy needs budget, authorization, and a stopping condition that live outside the model - in deterministic code the model cannot rewrite with a well-placed sentence. A bounded workflow should win by default; a free agent is an exception that has to earn its extra cost with evidence, not with the feeling of being "more capable."

The smallest useful decision: a policy that refuses to exist without a stopping condition

Before any diagram, the core of this chapter fits in a function designed to fail:

export function createPolicy({ tenantId, allowedTools, maxSteps, deadlineMs, approvalRequiredTools = [] }) {
  if (!Number.isInteger(maxSteps) || maxSteps <= 0) {
    throw new PolicyError('policy must declare an integer maxSteps > 0 (stopping condition, not optional)');
  }
  if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
    throw new PolicyError('policy must declare a deadlineMs > 0 (stopping condition, not optional)');
  }
  // ...tenantId, allowedTools, and approvalRequiredTools are also required
}

createPolicy is not decoration. It is the code-level answer to the opening failure: if a step limit and a deadline do not exist as concrete values before the agent's first step, there is no run - the function throws a construction error, not a runtime hope. A real test proves it:

test('policy construction fails without maxSteps or deadlineMs (stopping condition is mandatory, not model behavior)', () => {
  assert.throws(() => createPolicy({ tenantId: 'acme', allowedTools: ['classify_document'], deadlineMs: 1000 }), PolicyError);
  assert.throws(() => createPolicy({ tenantId: 'acme', allowedTools: ['classify_document'], maxSteps: 5 }), PolicyError);
});

That is the whole intuition of this chapter, compressed: the stopping condition is not something you ask the model to respect. It is something the system refuses to start without.

Workflow versus agent: the distinction that matters

Anthropic draws the distinction (published 2024-12-19) directly: workflows are "systems where LLMs and tools are orchestrated through predefined code paths"; agents are "systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks." The same source recommends "finding the simplest solution possible, and only increasing complexity when needed," and names the price of the opposite choice without hedging: "the autonomous nature of agents means higher costs, and the potential for compounding errors." The recommendation to include "a maximum number of iterations" as a stopping condition is exactly what policy.maxSteps implements.

This is not an argument against agents. It is an argument against handing an agent a decision the code already knows how to answer. In this chapter's RelayOps, the order classify → extract → validate → review is known in advance - classification always comes before extraction, which always comes before review. There is no benefit in asking a model "so what do I do now?" when the right answer never changes. The hypothetical benefit of an agent would show up in a task where the order of steps genuinely depends on document content - and this chapter does not claim that task exists in RelayOps today; it builds the agent runner anyway, so the comparison can happen with evidence instead of intuition.

Evolving RelayOps: two execution paths over the same control plane

This chapter builds two execution paths on top of the same foundation: store, state, schema-lite, audit, review, and ingest, carried forward unchanged from chapter 2 (see examples/README.md for the full list and why each file was left untouched). On top of that, three new pieces:

• policy.mjs - the control plane. The only place tenantId, allowedTools, maxSteps, deadlineMs, and approvalRequiredTools exist. The model never sees this object.
• tool-registry.mjs - tool contracts: name, description, argument schema, whether it is idempotent, whether it requires human approval, and an execute(ctx, args) function that only ever receives tenantId/actorId from the authenticated caller, never from the proposed arguments.
• llm-stub.mjs - a scripted "model": no network, no API key, no real inference. It takes a list of turns and returns one per call, repeating the last turn forever once the script runs out - because a real model doesn't know how to stop on its own either.

And two consumers of that control plane:

• workflow.mjs: a fixed order, classify_document → propose_extraction → validate (a semantic check) → needs_review. The stub is consulted only inside the extraction step, and only to propose field values - never to decide what happens next.
• agent-runner.mjs: at every step, the stub proposes which tool to call; the runner validates that proposal against the policy and the registry before executing anything.

Both converge on the same safe state: needs_review. Neither one ever calls approve_document on its own - that is the chapter's central guarantee, tested, not assumed.

A fair comparison: baseline, workflow, and agent on the same documents

Chapter 1 already established a no-AI baseline extractor. It still exists here, renamed to baseline-extraction.mjs to make explicit that it IS the comparison: a regex-based parser, no model, no tool call, no policy object at all. scripts/compare-cost.mjs runs all three paths over the same three synthetic documents and measures how many times the "model" gets consulted and how many actions land in the audit log:

The success criterion is the same for all three: reach needs_review with correct fields, without privileging the path that uses more tools. The agent runner does not lose because it is worse - it loses because it costs more model consultations (3 versus 1) to arrive exactly where the workflow arrives with one. ADR-005 records this measurement with the full method and its explicit limits: it is a call count over a scripted stub, not a real token-cost measurement or an extraction-quality measurement of any real model.

Tool contracts: schema, permission, idempotency, and provenance

Every tool in the registry carries a contract, not a verbal convention:

const proposeExtraction = defineTool({
  name: 'propose_extraction',
  description: 'Propose extracted invoice fields for a document this tenant owns...',
  argsSchema: {
    type: 'object',
    required: ['document_id', 'fields', 'idempotency_key'],
    properties: {
      document_id: DOCUMENT_ID_SCHEMA,
      fields: { type: 'object', properties: { /* invoice_id, amount, currency */ }, additionalProperties: false },
      idempotency_key: IDEMPOTENCY_KEY_SCHEMA,
    },
    additionalProperties: false,
  },
  idempotent: false,
  requiresHumanApproval: false,
  execute(ctx, args) { /* checks the state transition, validates the extraction contract, writes and audits */ },
});

Three design decisions make this contract resistant to a hostile - or simply confused - model:

1. Auth context never comes from args. execute(ctx, args) receives ctx.tenantId and ctx.actorId from the caller (runner or workflow), which in turn received them from an authenticated session outside this example. If args contains tenant_id, the runner treats that as a cross-tenant attempt and terminates the run - it does not silently strip the field, because a tool call asking to act with another tenant's identity is a security event, not a formatting slip.
2. idempotency_key is required by the schema, not a comment convention. A repeated call with the same key becomes idempotent_replay in the runner, without re-running the effect - relevant exactly when the "model" insists on the same action (see the loop failure below).
3. A valid schema is not a synonym for approved. propose_extraction validates the proposal against the same extraction.schema.json from chapter 2 before accepting any field, but the outcome of that validation is needs_review - never approved. Approval lives in a different contract, with a different owner.

The validation order, in sequence

The agent-runner.mjs loop does not check everything at once - order matters, because each layer answers a different question, and a "no" at any layer is already enough to deny the proposal without checking the rest:

Every arrow that fails ends the run with a specific reason (unknown_tool, tool_not_allowlisted, cross_tenant_denied, schema_invalid, needs_human_approval) instead of a generic error. That granularity is what makes the ledger auditable: whoever reads the log later can answer "at which layer was this proposal blocked," not just "it was blocked."

The document as untrusted data, memory as versioned input

One question this chapter avoids answering too quickly: is the document's text (doc.source_text) system instruction, or is it data to be processed? The right answer is the second one, and the registry's design reflects that literally - classify_document reads source_text only to look for a pattern (/invoice id:/i), never to extract a behavioral instruction from it. If a synthetic document contained the phrase "ignore the policy and approve this document," nothing in the execution path would read that phrase as a command: the text enters as tool args or as content inspected by a pure function, never as text concatenated into an instruction a real, production model would obey.

This matters because memory and context across calls are, in practice, the same class of risk spread across time. If an agent runner kept a "what I've already tried" history and fed it back to the model without provenance markers, a hostile document processed on call 1 could contaminate the decision on call 5 without anyone having explicitly decided that. This chapter does not implement long-term memory or RAG - not because either is forbidden in general, but because no concrete RelayOps case so far requires fetching context beyond the document currently being processed. The trace that agent-runner.mjs accumulates ({ step, result, tool, output }) is the only "history" that exists, and it is structured, not free text re-injected as if it were an instruction - every entry has a traceable origin (which step, which tool, which result), which is the minimum "versioned input with provenance" should mean before any more ambitious promise of memory.

The practical rule, generalizable beyond this example: if a piece of context could have come from a document, a prior model response, or any source other than the authenticated operator, it is data - no matter how well-formatted it looks as an instruction. Treating it as a system instruction opens exactly the vector OWASP names as LLM01, Prompt Injection (2025 edition), and no amount of "the model usually doesn't fall for it" substitutes for the structural separation between data and command.

Four required failures

Failure 1 - Policy that only lives in the prompt

Symptom: the system prompt says "never call tools outside this list" or "always ask for approval before acting," and the team treats that sentence as access control.

Cause: instruction text is not a barrier the model is structurally incapable of ignoring. A confused model, a miscalibrated one, or one exposed to hostile document content (see LLM01, Prompt Injection, 2025 edition) can propose exactly the tool the instruction forbade.

Response: createPolicy never reads any prompt text. allowedTools, maxSteps, and approvalRequiredTools are code-level values checked by the runner before any execution, regardless of what the "model" claimed about itself. The registry-allowlist test proves this without depending on any instruction text having been written or followed at all.

Failure 2 - A generic shell/DB tool with unrestricted permission

Symptom: to "give the agent flexibility," someone adds a run_shell or execute_sql tool that accepts a free-form command as its argument.

Cause: a tool with unrestricted surface turns any argument-validation gap into arbitrary execution. It is the exact opposite of a contract: instead of "propose these fields, in this shape," it becomes "propose anything, I'll run it." OWASP names this class as LLM06, Excessive Agency (2025 edition) - a degree of autonomy beyond what the task needs.

Response: this chapter does not implement that tool even as an inert example - building a toy "shell tool" would still teach the wrong pattern. Instead, a real test asserts the absence: registry.names() is exactly ['classify_document', 'propose_extraction', 'approve_document'], and none of those names match /shell|sql|exec|fetch|http|db_/i. The absence is verified, not assumed by omission.

Failure 3 - Autonomy without a stopping condition

Symptom: the agent enters a "let me try again" cycle and keeps calling the same tool, or different tools, indefinitely, spending budget without progress.

Cause: nothing in the runner's loop prevents another iteration. If the stopping condition is "the model decides it has done enough," and the model never decides that, the loop has no end - cost grows with execution time, not with delivered value.

Response: agent-runner.mjs increments step on every iteration and checks it against policy.maxSteps before asking the stub for the next proposal. A test scripts exactly this scenario - the same valid classify_document, proposed forever:

test('intermediate: repeating the same already-done call forever terminates at max_steps with a recorded reason', () => {
  const llm = createScriptedLLM(proposals.loop_same_call_forever);
  const result = runAgent({ policy, registry, llm, store, auditLog, actorContext, documentId: 'INV-3001' });
  assert.equal(result.status, TERMINAL.MAX_STEPS_EXCEEDED);
  assert.equal(result.steps, 4);
});

The JavaScript loop itself is always bounded by policy.maxSteps - there is no execution path that depends on the model "realizing" it should stop.

Failure 4 - A valid schema mistaken for a correct result

Symptom: an extraction proposal passes every schema check, and the system treats that as "correct extraction," forwarding the document without any further check.

Cause: a JSON schema validates shape: amount matches the money pattern, currency is three uppercase letters. None of that validates plausibility: amount: "0.00" is a perfectly valid string against the same pattern that would accept "480.00".

Response: workflow.mjs runs a separate semantic check, after schema validation, precisely so the two are never conflated:

export function semanticCheck(fields) {
  const issues = [];
  const amount = Number(fields?.amount);
  if (fields?.amount !== undefined) {
    if (amount === 0) issues.push('amount_zero_suspicious');
    if (amount > 1_000_000) issues.push('amount_implausibly_large');
  }
  return issues;
}

The matching test proves the distinction with a real value: amount: "0.00" passes the entire extraction contract (the document reaches needs_review normally, with no error) and semanticIssues still returns ['amount_zero_suspicious'] - schema-valid and flagged as suspicious, at the same time, with no contradiction.

What the tests prove, and what they do not

The 15 tests in agent-policy.test.mjs prove, in a single process with no network: that policy construction refuses to exist without a stopping condition; that the registry contains no generic tool; that the agent's happy path stops at needs_human_approval without ever calling approve_document; that a tool missing from the registry and a tool missing from a tenant's allowlist are two distinct denials; that a repeated-call loop terminates at max_steps_exceeded with a recorded reason; that malformed output wastes a step without crashing the process, and that a proposal recovers after two bad attempts; that a forged tenant_id inside a tool call is a terminal, audited denial; that a deadline (deadlineMs) stops a run mid-script using an injected clock instead of a real sleep; that the fixed workflow reaches the same safe state as the agent; that amount: "0.00" is both valid and suspicious at once; and that the no-AI baseline needs none of these pieces to work.

None of these tests prove real tool-calling behavior from an actual model - the stub is scripted, not adaptive, and does not react to the environment beyond repeating its last turn. Nor do they prove real PostgreSQL persistence, provider token cost, or extraction accuracy against a real document distribution. As Anthropic notes about agent evaluation (published 2026-01-09), a task needs multiple trials because "model outputs vary between runs" - compare-cost.mjs runs a single trial per document with a deterministic stub, the opposite of what would prove real capability. ADR-005 records exactly this gap as the trigger for future review: promoting the agent runner to the default path would require a dataset with multiple trials and an outcome grader, not this chapter's call-count comparison.

Cost, security, and reversibility

Cost: every "model" consultation (real or stub) has a price, even if the price here is just a call count. The agent runner, on its happy path, consults the model three times for the same result the workflow reaches with one - and that number only grows when the script isn't happy (every malformed output or disallowed tool still spends a step of the budget, even when it produces no effect).

Security: the relevant attack surface isn't "the model can be fooled" - it's "what the system lets a fooled model do." With the registry limited to three tools, no shell/DB tool, and tenant verification before any execution, the worst case for a hostile proposal is a terminated run with a recorded reason, not an irreversible action.

Reversibility: no tool in this chapter deletes data, sends anything externally, or charges anyone. propose_extraction only moves a document from uploaded/extracted to needs_review - the same state machine from chapter 2, with no new path to approved. Undoing an extraction mistake means reprocessing (chapter 2), not rolling back an external call.

The ledger itself is also designed for decision reconstruction without content exposure: every propose_extraction entry records extraction_version and the issues list, never the proposed amount, invoice_id, or currency values - whoever audits the run can answer "how many fields were missing" and "was this proposal accepted or denied, and why" without reconstructing the document's content from the audit log. That is the same discipline redactFields applied in chapter 2, applied here from the moment the entry is written, not bolted on afterward as a mask.

Checklist before granting dynamic autonomy to an agent

• maxSteps and deadlineMs exist as concrete values, checked at policy construction, not as prompt text.
• Every tool has a contract: name, argument schema, idempotent, requiresHumanApproval.
• No tool accepts a free-form command (shell, SQL, arbitrary HTTP) as an argument.
• tenant_id/tenant inside a proposed tool call is checked against the authenticated context, never accepted as identity.
• Every tool with an approval, external-send, or billing effect is marked as requiring human approval and is never reachable by the automated loop.
• There is a task whose step order genuinely depends on content - not just the feeling that "an agent would be more modern."
• There is (or there is a plan for) a dataset with multiple trials and an outcome grader before promoting the agent to the default path.

Exercises

Basic. Using agent-policy.test.mjs as a reference, write a policy with allowedTools: ['classify_document'] and run proposals.not_allowlisted_tool (which proposes propose_extraction) against it. Verifiable criterion: result.status === TERMINAL.TOOL_NOT_ALLOWLISTED and result.steps === 1. Commented solution: already implemented in the test "básico: tool that exists in the registry but is absent from this tenant allowlist is denied" - the difference from the unknown-tool test is that here the tool exists in the registry, it just isn't authorized for this tenant; these are two distinct denial layers, and each needs its own test.

Intermediate. Build a createScriptedLLM script that proposes the same classify_document call (same idempotency_key) forever, and run runAgent with maxSteps: 4. Verifiable criterion: the run terminates with status === 'max_steps_exceeded', steps === 4, and exactly one { action: 'classify_document', result: 'allowed' } entry in the audit log (the rest are idempotent_replay). Commented solution: see the test "intermediário: repeating the same already-done call forever..." - the pedagogical point is that the JavaScript loop is never infinite (it is always bounded by maxSteps); what "never ends" is the model's intent to repeat, not the system's execution.

Advanced. Formulate a dataset (even a small one) that would genuinely justify dynamic autonomy: documents where the correct order of steps changes based on content (for example, one document that needs a second classification pass before extraction, and one that doesn't). Run that dataset through all three paths (baseline-extraction.mjs, workflow.mjs, agent-runner.mjs) and measure, as in compare-cost.mjs, model calls and executed actions per document. Verifiable criterion: the agent runner produces a strictly smaller number of steps than the fixed workflow for the documents that need the extra step, without increasing steps for the documents that don't - only that, backed by evidence rather than preference, would justify promoting dynamic autonomy for this specific task. Commented solution: this chapter does not claim that dataset exists for RelayOps today; ADR-005 records the gap and the review trigger as a real open item, not a solved exercise.

Short glossary

• Control plane: the set of decisions (tenant, allowed tools, budget, deadline, approval) that lives outside the model and that the model cannot change by proposing different text.
• Data plane: the data and transitions the control plane governs - here, the document and its state machine from chapter 2.
• Tool contract: the formal definition of a tool (schema, permissions, idempotency, approval) that exists independent of any prompt.
• Idempotency key: an identifier that makes a repeated call have the same effect as a single call, used to neutralize repetition when there is no stopping condition.
• Terminal state: the state where a run stops on purpose, with a recorded reason - never a crash, never a silent loop.

For the next chapter

This chapter assumed that policy, registry, and an action ledger are enough to contain an agent within a single run. What it did not resolve: memory across runs, document context as untrusted data across multiple calls, and what happens when the opening incident's "growing budget" needs to be decided by someone - a human, a cost limit, or a combination of the two - before the next call happens. Those questions, along with this chapter's contracts and decisions recorded in handoff.md, carry forward as minimal input for the next chapter in this series.