An agent record API should answer a practical question: what happened between a person's request and the outcome the application delivered? A multi-step assistant may read sources, call tools, wait for approval, retry a failed operation, and create an external artifact. Saving only the final answer loses the sequence needed to diagnose failures, control repeated actions, and understand which steps were actually authorized.
This guide proposes an observable record model for agent workflows. It focuses on actions, inputs, results, and decisions the application can legitimately observe. It does not assume access to a model's hidden reasoning, and it does not equate a verbose transcript with a trustworthy audit. The aim is a compact record that explains the workflow without unnecessarily duplicating private content.
Give runs and steps separate identities
Use a run to represent one user-level task. Give each step its own identifier and link it to the run. A step might be a model attempt, a retrieval, a tool invocation, a validation check, or an approval wait. If a step is retried, preserve the attempts instead of making the latest attempt erase the earlier failure.
Keep the user's requested outcome distinct from the plan the agent proposes. Plans can change as information arrives, but the application still needs to know the authorized task boundary. Store a task revision when the person changes the request rather than pretending the original instruction always included the new scope.
For observability, OpenTelemetry describes traces made of spans and the parent-child relationships that connect work across a request. Spans can carry attributes, events, and status. The OpenTelemetry traces overview provides that foundational model. Your durable application record can reference trace identifiers without making sampled telemetry the only evidence of a business action.
Record observable events, not invented reasoning
Capture the operation requested, its authorized inputs or protected references, the result received, and the state transition the application performed. Those are observable facts. A model's brief explanation can be stored as model output when useful, but do not present it as a complete account of internal computation.
Use event names that describe what happened. Examples in your own schema might include tool_proposed, approval_requested, approval_granted, tool_started, tool_finished, and artifact_published. Define each event's meaning so two integrations do not use the same name for different boundaries.
Include timing with explicit semantics. A queued step, a running step, and a step waiting for a person have different sources of delay. Measure them separately when diagnosing performance. A run that took an hour because it waited for approval should not be reported as an hour of model computation.
Put authorization before execution
A tool proposal should pass through the application's authorization rules before it is executed. Check the current user, the requested resource, the action, and any scope limits. Do not let the tool name alone imply that every possible argument is allowed. Reading one approved document and exporting an entire workspace are different operations even when the same integration could technically perform both.
For actions requiring approval, show the actual proposed effect. An approval prompt should identify the destination and content of a message, the fields being changed, or the resources being removed. Bind the resulting approval to that specific operation or artifact revision. If the arguments change, reconsider approval rather than reusing it silently.
Record denials and cancellations as legitimate outcomes. An agent run that stops because access was denied can be behaving correctly. Do not measure success solely by whether the agent completed the maximum number of requested actions.
Make retries safe around external effects
A read-only retrieval and a message send need different retry policies. Repeating a retrieval may be acceptable; repeating a send can produce duplicates. Classify tools by their effects and define reconciliation before enabling automatic retries. A timeout is an uncertain observation, not proof that an external operation failed to happen.
Use an idempotency key when the external integration supports it, and keep that key attached to the logical action across attempts. Where it does not, consider checking for an existing result using a stable reference or routing the uncertain case for review. Do not invent an exactly-once guarantee from an at-least-once queue.
Test the awkward boundary: the external system accepted the action, but the worker crashed before recording success. A durable action record and a reconciliation path should allow the application to recover without blindly repeating the effect. This scenario matters more than a retry demonstration against a harmless test endpoint.
Separate checkpoints from exported artifacts
A checkpoint stores enough workflow state to resume a run according to your design. An artifact is something the user may inspect or use, such as a summary, note, report, or task list. Keep them separate. A checkpoint may contain temporary implementation details that should not appear in the user's export or public result.
Version checkpoints when the workflow definition changes. A resume operation should know which code and state assumptions it depends on. If an old checkpoint cannot be resumed safely, mark that limitation explicitly and provide a controlled restart or recovery path.
For delivered artifacts, retain the source and approval relationships that matter. A report created after several retrieval steps should point to the authorized source revisions, not merely the last model response. The MCP and LLM record guide explains how to distinguish retrieved resources from the context actually supplied to a model.
Budget the workflow before it expands
Set limits for tool calls, elapsed runtime, model attempts, and resource consumption appropriate to the task. Keep those budgets in the run configuration and report when a limit is reached. An agent that repeatedly revises its plan should not consume unbounded resources while the interface continues to promise progress.
Use explicit stopping conditions. A task can complete with a partial result and a clear list of unresolved items. It can also stop because the remaining work would exceed authorization or a budget. Those outcomes are more honest than producing an unsupported answer simply to satisfy a completion flag.
Measure budgets from the system's observations and mark missing data as unknown. Where costs are estimates, keep the pricing assumptions and estimate date available to the operator. Do not convert absent usage data into zero or advertise a fixed cost that the workflow cannot substantiate.
Keep records useful without overcollecting
Use references to protected content instead of placing every prompt, document, and tool result in ordinary logs. The person debugging a stalled run may need a step identifier and an error category, not the full contents of an interview or private message. Design diagnostic access around the investigation purpose.
Distinguish operational telemetry from durable action history. Sampling can be reasonable for performance traces, but a required approval or external effect record should not disappear merely because a trace was not sampled. Keep the two systems correlated without making their retention and completeness promises identical.
Track removal across artifacts and intermediate stores under your control. A deleted source can remain exposed through a generated summary or cached tool response if those relationships are ignored. Give cleanup workers enough lineage information to apply the chosen policy without guessing which records are related.
Test the entire failure story
Create scenarios for a denied tool call, a stale approval, a duplicate queue message, a cancelled run with a late result, and a worker restart after an external action. Inspect the resulting timeline as a support operator would. Can the record explain the outcome without reading unrelated private content?
Evaluate artifact quality separately from execution correctness. An agent can call every tool successfully and still deliver an unsupported summary. Conversely, it can produce useful partial work while correctly declining an unauthorized step. The agent workflow hub organizes these layers so a single green status does not hide different meanings of success.
Frequently asked questions
Is an agent trace a complete audit trail?
Not automatically. Define completeness, retention, access, and integrity requirements for the actions you need to account for. Performance telemetry may be sampled or short-lived. Use a durable application record for approvals and effects that require stronger guarantees, and describe those guarantees accurately.
Can a recorded run always be replayed?
No guarantee follows from recording alone. Tools, permissions, source content, and model behavior can change. Preserve the original observations and treat replay as a new controlled attempt, especially when any step can change an external system.
Conclusion: make each effect accountable
A strong agent record API connects the user's task, observable steps, current authorization, specific approvals, and delivered artifacts. It treats retries and uncertainty as design problems rather than logging details. With those boundaries in place, teams can investigate failures and improve agents without confusing activity with permission or fluent output with a verified result.
