> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand a run

> Follow model calls, tool results, approvals, and cancellation through one execution.

export const ExecutionExplorer = () => {
  const scenarios = [{
    name: "Answer",
    outcome: "The model asks for an order ID.",
    steps: [{
      title: "Request",
      owner: "Your application",
      detail: "The host sends input to the Agent.",
      value: 'await agent.run("Where is my order?")'
    }, {
      title: "Model",
      owner: "Model provider",
      detail: "Instructions ask the model to collect the missing order ID. No order tool is available in this example.",
      value: '{ "role": "assistant", "content": "What is your order ID?" }'
    }, {
      title: "Result",
      owner: "Your application",
      detail: "Check the run status before treating text as a successful answer.",
      value: '{ "status": "completed", "text": "What is your order ID?" }'
    }]
  }, {
    name: "Tool call",
    outcome: "The answer uses the delivery date returned by the tool.",
    steps: [{
      title: "Request",
      owner: "Your application",
      detail: "The request includes an order ID. The Agent is configured with lookup_order.",
      value: 'await agent.run("When will ORD-1042 arrive?")'
    }, {
      title: "Tool request",
      owner: "Model provider",
      detail: "The model requests a function. This is a proposal to execute, not a completed operation.",
      value: '{ "name": "lookup_order", "arguments": { "orderId": "ORD-1042" } }'
    }, {
      title: "Validation",
      owner: "SDK and host policy",
      detail: "Validate the schema and apply configured policy/approval. The tool implementation must also enforce domain access.",
      value: 'orderId: z.string()\n// Host-owned order authorization belongs in the integration.'
    }, {
      title: "Tool result",
      owner: "Your tool",
      detail: "The local demo catalog supplies the data. The result goes back into the model conversation.",
      value: '{ "status": "shipped", "delivery": "Friday", "refundable": true }'
    }, {
      title: "Response",
      owner: "Model → application",
      detail: "A later model call turns the result into an answer. Continue reading a stream until the Agent iterator ends.",
      value: '{ "status": "completed", "text": "ORD-1042 should arrive Friday." }'
    }]
  }, {
    name: "Approval denied",
    outcome: "No refund tool effect occurs. The model can still explain the denial.",
    steps: [{
      title: "Tool request",
      owner: "Model provider",
      detail: "The model proposes a simulated refund for the demo order.",
      value: '{ "name": "refund_order", "arguments": { "orderId": "ORD-1042" } }'
    }, {
      title: "Approval",
      owner: "Application operator",
      detail: "The approval callback shows the proposed action and receives an explicit decision.",
      value: '{ "approved": false, "reason": "Local operator decision" }'
    }, {
      title: "Denied",
      owner: "SDK",
      detail: "The tool body is not executed. Denial is returned to the model as a tool outcome.",
      value: 'simulatedRefundCount === 0'
    }, {
      title: "Response",
      owner: "Model → application",
      detail: "A completed conversational run can explain a denied action. Check the business outcome separately.",
      value: '{ "status": "completed", "text": "The operator did not approve the refund." }'
    }]
  }];
  const [scenarioIndex, setScenarioIndex] = useState(1);
  const [stepIndex, setStepIndex] = useState(0);
  const scenario = scenarios[scenarioIndex];
  const step = scenario.steps[stepIndex];
  return <section className="ag-explorer" aria-label="Illustrative execution explorer">
      <div className="ag-explorer-top">
        <span className="ag-eyebrow">Inside a run</span>
        <span className="ag-caption">Illustrative · no API calls</span>
      </div>
      <div className="ag-scenarios" aria-label="Choose an execution scenario">
        {scenarios.map((item, index) => <button type="button" key={item.name} aria-pressed={index === scenarioIndex} onClick={() => {
    setScenarioIndex(index);
    setStepIndex(0);
  }}>{item.name}</button>)}
      </div>
      <ol className="ag-step-list" aria-label="Execution steps">
        {scenario.steps.map((item, index) => <li key={item.title}><button type="button" aria-current={index === stepIndex ? "step" : undefined} onClick={() => setStepIndex(index)}><span>{index + 1}</span>{item.title}</button></li>)}
      </ol>
      <div className="ag-step-detail" aria-live="polite" aria-atomic="true">
        <div className="ag-step-heading"><strong>{step.title}</strong><span>{step.owner}</span></div>
        <p>{step.detail}</p>
        <pre><code>{step.value}</code></pre>
      </div>
      <div className="ag-explorer-bottom">
        <span>{stepIndex + 1} of {scenario.steps.length}</span>
        <div>
          <button type="button" disabled={stepIndex === 0} onClick={() => setStepIndex(stepIndex - 1)}>Previous</button>
          <button type="button" disabled={stepIndex === scenario.steps.length - 1} onClick={() => setStepIndex(stepIndex + 1)}>Next step →</button>
        </div>
      </div>
      <p className="ag-outcome"><strong>Outcome:</strong> {scenario.outcome}</p>
    </section>;
};

A run can contain multiple model calls and tool roundtrips. Inspect the sequence below to see why model completion, tool completion, and run completion are different events.

<ExecutionExplorer />

## The boundaries that matter

| Boundary | What happened | What it does not establish |
| - | - | - |
| Model finished | One provider call returned | The Agent may still need to execute tools |
| Tool returned | An implementation produced a result | The model has not necessarily answered the user |
| Run completed | The Agent reached a successful terminal outcome | A denied tool may have been explained; answer quality still needs evaluation |
| Client disconnected | The transport lost its caller | An external effect may already have completed |
| Process restarted | Memory in that process was lost | A remote operation's result may still exist |

`run()` gives you a final result. `stream()` gives you an iterator that may span several model calls. Consume it to completion or explicitly cancel/close it when its owner is done.

## Configure stopping behavior

Set tool-roundtrip and token/cost limits appropriate to the task. Pass a cancellation signal for connection-owned work. Tools that call external services should forward the signal where supported. [Cancellation](/agents/cancellation), [cost limits](/features/cost-autostop), and [execution policy](/agents/execution-policy) cover the controls.

## Inspect failures at the right layer

A provider can reject a request before a tool runs. Tool validation can reject arguments. Approval can deny the action. A tool can fail after contacting a remote service. These require different responses; retrying the whole run indiscriminately can repeat a side effect.

For diagnostics, start with run status, correlation IDs, model configuration, tool outcome, and timing. [Observability](/observability/overview) defaults to metadata; configure content capture deliberately. See [recovery](/ship/recovery) for outcomes that cannot be inferred from a local error alone.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.