In short. One call, UseExperienceCapture, wraps a Microsoft Agent Framework (MAF) agent so that every
invocation is recorded as an Experience Run: the attempt, each tool call with its arguments and result, and how the
invocation ended (success, failure, cancellation, or a stream the caller stopped reading). Everything goes through
Core's sanitizer before it is kept, so unsafe content is refused rather than stored. Capture never changes what the
caller sees, and it never throws into the agent. By default one invocation is one run; you can opt in to recording
retries as attempts of one run, so a later lesson sees the failure and the fix together.
Package: AgentExperience.MicrosoftAgentFramework, over Core's IExperienceCaptureService. It requires
Microsoft.Agents.AI 1.22.0 or any later 1.x (declared [1.22.0, 2.0.0)).
The one-call setup (services.AddAgentExperience(...) and
UseAgentExperience(provider)) wires capture for you, with safe sanitization and limits, the run described by your
TaskId (the agent's name when you set none), the resolved identity's scope and the user's own words, and verification through Verify. Adjust any option
below through its options.Capture hook. Wired by hand, it looks like this:
using AgentExperience.Core.Capture;
using AgentExperience.Core.Sanitization;
using AgentExperience.MicrosoftAgentFramework;
using Microsoft.Agents.AI;
IExperienceCaptureService capture = new InMemoryExperienceCaptureService(
new DefaultSanitizer(sanitizationOptions),
captureLimits,
TimeProvider.System); // the clock completed-run retention is measured on
AIAgent agent = chatClientAgent
.AsBuilder()
.UseExperienceCapture(capture, new ExperienceCaptureOptions
{
ResolveRun = context => new ExperienceRunDescriptor(
TaskId: "triage-ticket",
Scope: hostScope, // established by the host, never taken from model output
TaskDescription: context.DerivedTaskText), // the user's own words; redact first if needed
OnCaptureFailure = failure => logger.LogWarning("Capture failed at {Stage}: {Reason}", failure.Stage, failure.Reason),
})
.Build();
var response = await agent.RunAsync("...", session);context.DerivedTaskText is the user's latest message (with the one before it when the latest is a short follow-up),
cleaned up and cut to 512 UTF-16 code units, or null when there is none; the rule is in
Injection: the task text. The description becomes the record's task summary, which
text search matches alongside the task ID and the lesson, so leaving it null leaves a record findable only by those
two. The derived text is the user's own words and is stored unsanitized, as TaskDescription always has been (and
a model-backed reflector is shown it): a host whose prompts can hold secrets or personal data should pass it through
its own redaction before returning it. Nothing sets the description for you.
Capture and injection can derive different text for the same turn. ResolveRun sees only the invocation's new
input, never the session's chat history, while the injection provider also reads the replayed history. The two
differ exactly when the latest request is shorter than ExperienceTaskText.FollowUpThreshold (64) UTF-16 code units
and the new input holds no earlier user message, but the history does: for "and retry" after "Deploy service X to
prod", injection retrieves on Deploy service X to prod — and retry while capture describes the run as and retry.
To describe the run the same way, derive from the history your host keeps plus the new input:
ResolveRun = context => new ExperienceRunDescriptor(
TaskId: "triage-ticket",
Scope: hostScope,
// previousTurns: the user messages your host kept from earlier turns of this conversation.
TaskDescription: ExperienceTaskText.Derive([.. previousTurns, .. context.Messages])),Messages you pass this way carry no ChatHistory stamp, so they count as input, and the latest request is still the
last user message with text: put the new input last. (An image-only new input then yields the last kept turn rather
than null.) The property is computed on first read from a snapshot of
context.Messages, enumerated once; if enumerating it throws, that first read throws and later reads return null.
Call UseExperienceCapture first on the builder so capture is the outermost layer. It registers:
- Agent-run middleware. It opens the run before the inner agent executes and completes it exactly once, on success, failure, cancellation, or when a streaming consumer stops early — unless you asked to keep the run open for a further attempt (see Retries as attempts of one run).
- Function middleware (when
CaptureToolCallsistrue, the default). It records each tool call, including its result or exception, into the run for that invocation.
Every recorded value goes through the IExperienceCaptureService you pass in, so its sanitizer and limits apply
unchanged. This adapter never evaluates, reflects, or persists anything itself; when you configure finalization it
hands the completed run to Core's ExperienceFinalizationService, which owns all of that (see
Finalization).
When the caller passes a session, the run ID is written to it under
ExperienceCaptureAgentBuilderExtensions.RunIdStateKey ("AgentExperience.RunId") as a "D"-formatted GUID
string. Nothing else is written to the session. The run ID is never placed in AgentRunOptions.AdditionalProperties,
because MAF forwards those to the model provider.
Sanitization is the first gate, and it is fail-closed at capture time rather than at storage time. The default
sanitizer applies a per-Kind policy (tool arguments are SanitizationKinds.ToolArguments, results and errors
SanitizationKinds.ToolResult, carried in its one SanitizationKinds.ValueField field): a field you allowlisted is
kept, a field you marked secret is redacted as a whole value, and anything else is dropped. A Kind with no policy at
all is rejected, never passed through. AgentExperienceDefaults.Sanitization (in AgentExperience.Core.DependencyInjection)
is a safe starting point: it keeps no tool argument until you allowlist it by name, keeps results and errors, and
redacts secret-named fields (password, secret, token, apiKey, api_key, authorization, connectionString,
in any case).
When content cannot be sanitized, AppendAttemptAsync returns AppendAttemptOutcome.SanitizationRejected and the
sanitizer's own Reason, the attempt is not recorded, the run stays open, and nothing is stored anywhere —
there is no database involved, so there is no partial write and no persisted denial record to reconcile later. The
host is told the decision and why, and can correct and resubmit the same attempt ID; the rejected ID is not tracked,
so a corrected resubmission succeeds. Unsafe content therefore never reaches an Experience Record, and never becomes
something a grant could later share.
Content is rejected when it breaks a limit (depth, field count, value or field-name length), uses ., [ or ] in
a field name, or holds a number that JSON cannot carry. That last case covers an allowlisted value that is a double,
float, Half, NFloat or Complex holding NaN or an infinity, or a JsonElement number beyond a double's range
(such as 1e400, or an integer literal that rounds past double.MaxValue). A record holding such a number could be
stored but never written as JSON again. The reason names the field's path, never its value. A secret-named field
holding one is still redacted without being read, and a field that is not allowlisted is still dropped. Other value
types (integers, bool, decimal, Guid, dates, enums, and your own structs) are kept as opaque leaves, unexamined:
a custom struct that holds a non-finite number is not detected, so allowlist only fields whose shape you know. If you
supply your own ISanitizer, it must refuse non-finite numbers too, or a record that cannot round-trip can be stored.
Sanitization is name-based: it cannot guarantee that every arbitrary secret hiding in free text is detected. See
DefaultSanitizer.
| Option | Default | Meaning |
|---|---|---|
ResolveRun |
required | Maps messages, session, and agent to a task ID, scope, task description (context.DerivedTaskText is a ready one), and optionally the ID of a run this invocation continues. If it throws or returns a null descriptor, task ID, or scope, the invocation runs uncaptured and the failure is reported. |
ShouldCompleteRun |
always complete | Decides, after the attempt is recorded, whether this invocation's run is finished. false keeps it open for a further attempt. The default is exactly the behaviour every host had before continuation existed. |
MaxOpenRunDuration |
5 min | How long a run may stay open across invocations before the adapter completes it itself and reports. Must be positive and at most uint.MaxValue - 1 milliseconds. |
MaxAttemptsPerOpenRun |
8 | The most attempts a run the adapter is holding open may accumulate before it is completed anyway and reported. Must be positive. Separate from the capture service's own CaptureLimits.MaxAttemptsPerRun; whichever is reached first ends the run. |
Environment |
machine name + RuntimeInformation |
Environment fingerprint recorded on every run. |
CaptureToolCalls |
true |
Registers function middleware. Requires a ChatClientAgent. |
ClassifyToolResult |
none | Says that a tool call which returned failed: return an error class to record it as failed, or null to record it as returned. See Tools that report failure in their result. |
FinalizationTimeout |
5 s | Upper bound on the whole post-invocation step: appending the attempt, completing the run, and — when FinalizationService is set — finalizing it into a durable Experience Record. With finalization configured this bounds database round trips, not just in-memory capture, so 5 s may be too tight. Must be positive and at most uint.MaxValue - 1 milliseconds. It uses its own token, never the caller's. |
OnCaptureFailure |
none | Called when capture fails, at most once per failure stage per run. The stages are ResolveRun, StartRun, Finalize (recording the attempt and completing the run in memory), ToolCall, Finalization (turning the completed run into a durable Experience Record), RecordExposure (recording which records the context provider delivered into the run), ToolResultClassification (ClassifyToolResult threw or named an invalid class), Embeddings (the one-call setup cannot use the embedding generator), Recall (recall at the moment of failure has no signature source) and RunStore (the run was completed, but the run store could not keep it for finalizing later). Exceptions it throws are swallowed. |
FinalizationService |
none | Core's ExperienceFinalizationService. When set, each successfully captured run is finalized into a durable Experience Record. Requires exactly one of ResolveFinalizationAsync and ResolveFinalization. |
ResolveFinalizationAsync |
none | Builds the FinalizeExperienceRequest for one completed run, awaited with the FinalizationTimeout-bounded token (never the caller's), so it can run checks or read CI for the evidence. Return null to skip finalizing that run. The preferred form. A throw or a faulted task is reported through OnCaptureFailure exactly as a synchronous throw is. |
ResolveFinalization |
none | The synchronous form of ResolveFinalizationAsync, unchanged. With FinalizationService set, exactly one of the two is required; setting both, or either without FinalizationService, throws ArgumentException at UseExperienceCapture. |
OnRunFinalized |
none | Receives every FinalizeExperienceResult, durable or not — including a host decision such as StorageDenied, which is not a capture failure. Not called once finalization has overrun FinalizationTimeout. Exceptions it throws are swallowed. |
TimeProvider |
TimeProvider.System |
Timestamps, durations, and the finalization timeout. |
NewId |
Guid.NewGuid |
Run, attempt, tool-call, and completion-event IDs. Must be thread-safe. |
By default one invocation is one run: it is opened, its single attempt is recorded, and it is completed. A retry is therefore a second run — the failed one finalizes on its own (quarantined, never reusable) and the successful one is reflected on as if the failure never happened. That makes the library's own premise, learning from failure, unreachable through this adapter.
Opt out by naming the run the invocation continues and saying when the run is finished. One retry cycle is one run: mint its identifier when the cycle starts, and a fresh one for the next cycle. A completed run is final, so an identifier reused after its run closed is refused and every later invocation naming it runs uncaptured, for as long as the capture service still holds that run (see How long runs are kept).
Guid? currentRun = null; // the run of the retry cycle in progress
var agent = innerAgent.AsBuilder()
.UseExperienceCapture(capture, new ExperienceCaptureOptions
{
ResolveRun = _ => new ExperienceRunDescriptor("triage-ticket", hostScope, ContinuesRunId: currentRun),
// Decided on the attempt's own recorded result, inside the invocation, so the attempt that
// succeeds is the one that closes the run.
ShouldCompleteRun = ctx => (ctx.Result is { } text && Check(text)) || ctx.AttemptCount >= 3,
MaxAttemptsPerOpenRun = 3,
MaxOpenRunDuration = TimeSpan.FromMinutes(2),
FinalizationService = finalization,
ResolveFinalizationAsync = (ctx, cancellationToken) => BuildRequestAsync(ctx.Run, cancellationToken),
}, out var captureLifetime)
.Build();
async Task RunCycleAsync(string prompt)
{
currentRun = Guid.NewGuid(); // a new cycle, so a new run
for (var attempt = 1; attempt <= 3; attempt++)
{
var response = await agent.RunAsync(prompt);
if (Check(response.Text))
{
break;
}
}
}
// At teardown, so no open-run bound fires into a host that is shutting down.
captureLifetime.Dispose();The second invocation of a cycle appends attempt 1 to the same run, so the reflection eventually produced sees the
failure and the success together; the next call to RunCycleAsync starts a new run. Finalization is deferred with the
run: an open run is never handed to FinalizationService, because only a completed run can become a durable
Experience Record. The example keeps the cycle's identifier in one field, so it runs one cycle at a time; a host
running several at once keeps each cycle's identifier with that task's own state and returns it from ResolveRun.
The rules this comes with.
-
A continuation ID that names a run with a different task ID or scope, or a run that has already been completed, is a conflict: that invocation runs uncaptured and the refusal is reported through
OnCaptureFailureat theStartRunstage, exactly as a colliding identifier always has been. A run finalizes once and is never reopened. Once the capture service has dropped a completed run (see How long runs are kept), though, its ID names no run, so the next point applies: a new run is opened under it. -
A continuation ID that names no run at all simply opens a new run under it. An all-zeros ID (
Guid.Empty) is refused at theResolveRunstage: it is a default-valued field, not a run, and accepting it would pile every invocation onto one run. -
A continuation joins a run; it never rewrites it. The run keeps the task description, environment, provenance (its
CorrelationIdincluded) and start time it was opened with, and the continuing invocation's own are dropped. So an ID reused by accident, with the same task and scope, is merged rather than refused, and the two invocations are reflected on as one run. Matching task and scope is the only check, and the capture service keeps an open run until it completes, so the collision window is that long. Minting the ID per cycle is what prevents it. -
Two invocations cannot capture on one run at once — including while the invocation that opened the run is still in flight, since its ID is readable from the session the moment the run exists. The second is refused and runs uncaptured, rather than interleaving a second half-recorded attempt.
-
What the default path costs. To make the rule above hold for the invocation that opens a run, every captured invocation takes a transient claim (one entry in the registration's open-run ledger) for as long as it is in flight, the default single-invocation path included. It also arms its run's duration bound, one timer on your
TimeProvider, as soon as the run is opened (see the next point). When the invocation releases the run, the claim is removed and the timer is disposed. A default invocation, which completes its own run, therefore leaves no entry and no timer behind. In a microbenchmark on one machine (not part of this repository), creating and disposing the timer withTimeProvider.Systemtook about 45 ns and 120 bytes. Together with keeping the timer from capturing the invocation'sExecutionContext, it added about 200 bytes to an in-memory invocation through the adapter (about 5.7 KB allocated, 7 to 10 µs), with no time difference above the noise. That is far below the cost of one model call. A run that is left open keeps its entry and its timer until the run is completed, and so does a run whose default finalization failed or overranFinalizationTimeout, because whether that run was completed is unknown. -
An open run is bounded from the moment it opens, and never silent. It holds captured payload in memory, so the adapter completes it, reporting through
OnCaptureFailure, in any of these cases:- it reaches
MaxAttemptsPerOpenRun; - it has been open for
MaxOpenRunDuration. A timer on yourTimeProviderenforces this, armed when the run is opened, so neither a host that never invokes again nor an invocation that never returns can leave a run open; - an attempt could not be recorded at all;
- the run could not be read back to ask
ShouldCompleteRun; ShouldCompleteRunthrows.
There is no path where a run stays open because a host forgot to close it. If the duration bound fires while an invocation is holding the run, the close is handed to that invocation once, and the bound re-arms for one further period. If the invocation has still not come back by then, the run is closed underneath it: a hung inner agent, a streaming consumer that abandoned its enumerator without disposing it, or the invocation that opened the run and never returned. A run that was completed normally is never reported as closed at its bound. The one exception is a
TimeProviderwhoseCreateTimerthrows. That is reported at once, the run has no bound while its invocation is in flight, and the run is completed when the invocation returns instead of being left open. - it reaches
-
So an invocation can hold a run for at most twice
MaxOpenRunDuration, on the default path too. The only addition to that is the time the close itself takes, which is bounded byFinalizationTimeout. A default invocation still running when one bound period ends is handed the bound and completes its run normally when it returns. One still running at twice the duration has its run completed asCancelledunderneath it, and that is reported. When it does return, its answer is untouched, but its attempt is refused by the completed run and that is reported too. SetMaxOpenRunDuration(default 5 minutes) above the longest invocation you expect. -
Bound callbacks arrive off the invocation. A run closed by
MaxOpenRunDurationis completed, reported throughOnCaptureFailure, and finalized (withOnRunFinalized) from a timer callback on a thread-pool thread. That is never the thread of an invocation, including a hung one still holding the run. This holds withTimeProvider.Systemand with any provider that runs timer callbacks asynchronously. A fake clock that fires a due timer synchronously insideCreateTimerorChangeruns the callback on whichever thread called it. Both callbacks must be thread-safe.Use the
UseExperienceCapture(..., out var captureLifetime)overload and dispose the handle at teardown. Disposal cancels every armed bound, including one armed at open for an invocation still in flight. After disposal, the adapter reports nothing more through its bounds and starts no finalization. Disposal does not wait: a close that was already inside your capture service when you disposed still finishes writing its completion, and a callback already running is not interrupted. A run still open at that moment is abandoned: nothing is written and no timer reports it, and an invocation still in flight says so as it returns. Later invocations through that agent run uncaptured and say so. The default configuration can have bounds to dispose too: a hung invocation's, and one whose finalization failed. -
The run this registration is holding open belongs to that registration. Build the agent once and reuse it; two independently built agents do not share continuations.
The default capture service (InMemoryExperienceCaptureService) holds runs in process memory (and, with a run store,
also keeps each completed run durably: see Finalizing later), so it bounds how many completed runs
it keeps:
- By age. A completed run is dropped once it is older than
CaptureLimits.CompletedRunRetention(default 24 hours), measured from when the service recorded the completion, on theTimeProvider's monotonic timestamp, so a wall-clock change does not move it. ThroughAddAgentExperienceCorethe service uses the registeredTimeProvider(orTimeProvider.Systemwhen none is registered); constructed directly, it uses the one you pass (TimeProvider.Systemwith the two-argument constructor). - By count. Once more than
CaptureLimits.MaxRetainedCompletedRuns(default 10,000) completed runs are held, the earliest completed is dropped first. - Only when the service is called. No timer runs: the bounds are applied at the start of every call to the service, before it answers. An idle host keeps what it held until its next capture call.
- Finalization does not drop a run. While a run is held, retrying its finalization still returns
AlreadyFinalized, and reusing its ID is still a conflict.
services.AddAgentExperienceCore(sanitizationOptions, new CaptureLimits(MaxAttemptsPerRun: 10, MaxToolCallsPerAttempt: 50, MaxResultLength: 4_000, MaxErrorLength: 4_000)
{
MaxRetainedCompletedRuns = 500, // about 4 GB in the worst case with these limits (see below)
CompletedRunRetention = TimeSpan.FromHours(6),
});A dropped run answers every call exactly as a run that never existed: TryGetRun returns false, the other calls
report RunNotFound, and StartRun with its ID opens a new run. So anything that needs the captured run must happen
while it is held:
- Finalize, and retry finalization, within the window. After the run is dropped a retry returns
RunNotFound(the stored record is unaffected), and a continuation that reuses the ID opens a new run. - Use a fresh run ID for every run. A continuation that reuses the ID of a run already dropped opens a new run,
but finalizing that run returns
AlreadyFinalizedfor the earlier record (the record ID derives from the run ID and scope), so the new run's content is not stored. - Evidence naming a run that has not been finalized must arrive within the window. Confidence verification answers from the finalized record when there is one, and falls back to the captured run only for a run with no record yet; once such a run is dropped, evidence naming it can no longer be verified against it.
Sizing MaxRetainedCompletedRuns. The stored text of one run is bounded by CaptureLimits: at most
MaxAttemptsPerRun × (1 + MaxToolCallsPerAttempt) × (MaxResultLength + MaxErrorLength) characters of results and
errors (two bytes each in .NET), plus tool-call arguments and the attempt requests kept to recognise a retried
append, neither of which CaptureLimits caps in length. With the example above that is up to
10 × 51 × 8,000 = 4.08 million characters, about 8 MB, per run, so the example's 500 runs come to about 4 GB at
worst; at the default of 10,000 the same limits allow about 80 GB at worst. Most runs are far smaller. Set the count
to what your memory budget allows at the worst case, or at a realistic per-run size you have measured, and high
enough to cover the completed runs that finish within the time your host takes to finalize them.
Open runs. The bounds above never drop an open run. The service bounds open runs separately, and never drops one without completing it first:
- By count, on by default. At most
CaptureLimits.MaxOpenRuns(default 10,000) runs are open at once. Past it, aStartRuncall that would open a new run returnsStartRunOutcome.CapacityExceededand stores nothing. A call that continues an open run is never refused, and a run frees its slot as soon as it completes. The MAF adapter reports a refusal throughOnCaptureFailure(stageStartRun) and runs the invocation uncaptured. - By age, off by default. Set
CaptureLimits.MaxOpenRunAgeand the service itself completes an open run older than it (measured on the monotonic timestamp from when the service opened the run) asCancelled, withEndedAtset to theTimeProvider's current time (never earlier than the run'sStartedAt). From then on it is a completed run, kept and dropped under the bounds above. A host that later completes it under its own completion event ID getsConflict, as for any completed run, and so does an attempt appended to it. Like the other bounds, it is applied only when the service is called, soEndedAtrecords when the service noticed the expiry, on its first call after the run became due, not when it became due. - A run the age bound cancels is never finalized or reported by the service. Nothing calls finalization for it
and nothing tells the host it happened. A direct caller that wants a durable record of a run must complete and
finalize it itself before
MaxOpenRunAgepasses.
The MAF adapter already completes a run left open for MaxOpenRunDuration (see above), so the age bound matters to
a caller that uses IExperienceCaptureService directly. Such a caller should still complete every run it opens; the
age bound is the backstop for the ones it does not. If you set both, set MaxOpenRunAge longer than twice
MaxOpenRunDuration plus FinalizationTimeout, the longest an invocation can hold a run (see above), so the
adapter's own close, with the run's real outcome and its report, always comes first.
new CaptureLimits(MaxAttemptsPerRun: 10, MaxToolCallsPerAttempt: 50, MaxResultLength: 4_000, MaxErrorLength: 4_000)
{
MaxOpenRuns = 1_000,
MaxOpenRunAge = TimeSpan.FromHours(1),
};Sizing both counts together. An open run can hold the same worst case per run as a completed one, so the service
can hold up to MaxOpenRuns + MaxRetainedCompletedRuns runs at once, not only the completed ones. At the defaults that
is 20,000 runs: with the per-run limits of the earlier example (about 8 MB per run at worst), about 160 GB at worst,
twice the completed-only figure above. Size the two counts so their sum fits your memory budget.
The default capture service keeps runs in process memory, so a run can be finalized only by the process that captured
it. When the verdict arrives later -- a CI result, a merged pull request -- after that process has ended, register an
IExperienceRunStore:
.UseSqlite(path)registers one (SqliteExperienceRunStore, in the same file as the records).- On PostgreSQL it is opt-in:
services.AddAgentExperiencePostgresRunStore(), after migrating to0032and re-running the privileges call. It is not available in crypto-shredding mode, because a stored run is not sealed.
With a run store registered, AddAgentExperienceCore wires it into both services:
- The capture service writes each run through as it completes it.
CompleteRunAsyncsaves the completed run -- its attempts already sanitized: capture sanitized every attempt before it kept it -- under its completion event before it returns. The run'sTaskId,TaskDescription,EnvironmentandProvenanceare stored exactly as the host passed them toStartRun, which sanitizes none of them: keep secrets out of them. Nothing is written on the path of a tool call or an attempt. - A save never fails the run, and never holds it up for long. The save runs off the caller's thread and is awaited
for at most
ExperienceRunStoreOptions.SaveTimeout(5 seconds by default; SQLite's own wait for a busy file isSqliteStorageOptions.RunSaveBusyTimeout, 2 seconds). A save that throws, is refused or times out leaves the completion standing, andCompleteRunResult.RunStoreFailuresays why (the MAF adapter reports it throughOnCaptureFailureat stageRunStore). The caller's own cancellation surfaces asOperationCanceledException, as everywhere on the API, with the completion already recorded. Completing the run again with the same completion event saves it again. A run the service completes itself because it stayed open pastMaxOpenRunAgeis not saved. - Which runs are kept is the host's call. Register an
ExperienceRunStoreOptionswithShouldPersistRun(say,run => run.ExecutionStatus == RunExecutionStatus.Failed) to keep only some runs; the default keeps every one. - Finalization reads a run the capture service no longer holds from the run store, within the request's
authorization, and then does exactly what it does for a run held in memory: the same evaluation against the request's
own closed round and evidence, the same storage decision, the same derived record and event IDs. Finalizing the run
twice, or from two processes at once, makes one record (the second is the usual replay). After a durable outcome it
marks the stored run finalized (best effort). When the host's storage decision refuses the run
(
StorageDenied), its stored copy is deleted too; a failed delete is reported onFinalizeExperienceResult.RunStoreFailure(and by the MAF adapter at stageRunStore). A run refused asNotAuthorizedis left stored: the caller had no authority over its scope, so it may not delete it either. - Erasure is final. Erasing a record turns the stored run it came from into a payload-free tombstone (or writes one), so a later save of that run -- a capture retry -- is refused as a conflict and the run never comes back.
// Process 1, the agent's run: captured and completed as usual; the run is now in the file.
// Process 2, when CI reports back:
var result = await finalization.FinalizeAsync(new FinalizeExperienceRequest(
runId, authorization, closedRound, requiredChecks, evidence, artifactRevision, StorageDecision.Permit, timeProvider.GetUtcNow()));IExperienceRunStore.ListUnfinalizedAsync pages through a scope's runs still waiting for a verdict (optionally only
those that ended before an instant), and DeleteAsync removes one: delete runs after finalization, or after a retention
of your choosing -- nothing sweeps them for you. Erasing a record also deletes the stored run it came from.
| Agent | Run lifecycle | Tool calls |
|---|---|---|
ChatClientAgent |
yes | yes |
Other AIAgent subclasses, A2AAgent |
yes, with CaptureToolCalls = false |
no. Build() throws if CaptureToolCalls is true, because MAF function middleware needs a FunctionInvokingChatClient. A2A tools run server-side. |
ChatClientAgent with UseProvidedChatClientAsIs = true and a raw client without FunctionInvokingChatClient |
yes, with CaptureToolCalls = false |
not supported |
- One invocation is one attempt. That attempt holds every tool call from the invocation, ordered by
start time, including calls MAF runs concurrently (
AllowConcurrentInvocation). MAF's own function-calling loop iterations are not split into separate attempts. By default that attempt's run is completed with the invocation, so one invocation is one run; a host that opts into continuation gets several attempts on one run instead. - Attempt result. On success the attempt
Resultis the responseText. For streaming, it is the concatenatedTextof the yielded updates. Tool-callResultis the tool's return value converted to a string, andArgumentsare theFunctionInvocationContext.Arguments. All of it is raw input to the capture service's sanitizer. - Error classification.
- Errors are recorded as the exception's full type name only, never its message, because messages often embed arguments or secrets.
- An
OperationCanceledExceptionmarks the runCancelledonly when the caller's cancellation token is cancelled. Any other exception marks itFailed, including anOperationCanceledExceptionfrom a provider orHttpClienttimeout. - A streaming consumer that stops reading early marks the run
Cancelledwith no error. It is finalized when the enumerator is disposed.
- Tool exceptions are recorded, then rethrown unchanged. MAF then turns them into an error result for the model, and the run continues.
- A tool that returns is recorded as returned, whatever its result says, unless
ClassifyToolResultnames an error class for it (see Tools that report failure in their result). - Capture never changes what the caller sees. The response, streaming updates, and exceptions are exactly what the agent would produce without capture. Capture does not wrap or re-execute tools, retry, or keep its own session store.
- Capture failures are reported through
OnCaptureFailureand never thrown. They include a resolver exception, a non-success capture outcome, a capture exception, a finalization timeout, and a failed Experience Record finalization. Note the two similarly named stages:Finalizeis the in-memory capture step (append the attempt, complete the run), whileFinalizationis turning that completed run into a durable Experience Record. Each failure stage is reported at most once per run, so an earlier tool-call or session-write failure never hides a later finalization failure. - Finalization. Completion is attempted even when appending the attempt fails. If finalization times out, the run may be left without an attempt or completion.
- Latency. Finalization is awaited before the response is returned, the exception rethrown, or the stream ends, so
it can add up to
FinalizationTimeoutof caller-visible latency. That includes invocations that failed or were cancelled. - Undisposed streams. A streaming run is finalized when its enumerator finishes or is disposed. An enumerator that
is never disposed (for example, abandoned without
await foreachorDisposeAsync) holds its run open until the open-run bound closes it: at most twiceMaxOpenRunDuration, reported throughOnCaptureFailure(see Retries as attempts of one run). - Late tool calls. A tool call that finishes after its run was finalized is not recorded. This can happen after an early stream break.
Only a tool that throws is recorded as failed. Many tools report failure in their return value instead: an exit code,
{"ok":false}, an HTTP status in the body. Such a call is recorded as returned, so a later agent's Tried: line marks
it [returned] and reads as if that approach worked (see Injection).
ClassifyToolResult lets the host say which returned results are failures.
Naming rule: the class you return must be one token a Tried: line can show: a type-like name ending in Error
or Exception (LockHeldError, ExitCodeError) or the exit N form (exit 3). Anything else is recorded as
ToolReportedError. Surrounding white space is trimmed, but the class is case-sensitive and must be the exact
normalized form: exit 3, not Exit 3 or exit=3.
var scope = new Scope("tenant-1", "app-1", "project-1");
var options = new ExperienceCaptureOptions
{
ResolveRun = context => new ExperienceRunDescriptor("triage-refund", scope, context.DerivedTaskText),
// The tool returns "exit=<code>". A non-zero code is a failure, named by its code: "exit 3".
ClassifyToolResult = context =>
context.ToolName == "run_refund_check"
&& context.Result?.ToString()?.Trim() is { } text
&& text.StartsWith("exit=", StringComparison.Ordinal)
&& text != "exit=0"
? "exit " + text["exit=".Length..].Trim()
: null,
};Ready-made classifiers. ExperienceToolResultClassifiers.ExitCode(toolNames) returns exit N for a non-zero
exit code (exit=N, exit N, exit code N, exit status N, exited with code N, returncode=N, "exitCode": N,
"exit_code": N, "returnCode": N, "return_code": N), and HttpStatus(toolNames) returns HTTP N for a status
from 400 to 599 (a leading HTTP N or status N, or "status": N or "statusCode": N); both return null
otherwise. Matching ignores case.
- A JSON object (a
JsonElement, a string that parses as one, or any other object, serialized as capture serializes it) is read by its top-level properties only, whatever its size: the first ofexitCode,exit_code,returnCode,return_code(orstatus,statusCode,status_code) holding a number or a numeric string. An exit code quoted inside its output does not count. A JSON array names no code. - Other text (a string, a
TextContent, or a list of them) is matched whole up to 1 MiB (beyond that, its first and last 64 KiB), and the last match counts, so a finalexit=1wins over an earlier step'sexit 0. - A non-zero exit code no token can carry is recorded as
ToolReportedError: more than six digits (Windows status codes such as-1073741819) or not an integer (1.0,1e0). Zero in any form is success. - Give the tool names (ordinal match) to leave every other tool's result alone; with none, a classifier applies to every tool.
Under the one-call setup, set one with options.Capture = capture => capture.ClassifyToolResult = ExperienceToolResultClassifiers.ExitCode("run_tests");, and see
Built-in verifiers to verify a run by its last test call.
The classifier gets an ExperienceToolResultContext: the call's ToolCallId (which tells concurrent calls apart), the
tool's registered ToolName, a read-only view of the captured Arguments, and the raw Result the tool returned,
before it is converted to text (a string, a JsonElement, or any other object). It gets no other model text.
The arguments are the raw ones, before sanitization, so secrets the model passed reach the classifier: never log or
keep them. The dictionary is read-only, but Result and the argument values are the live objects the model works
with: do not change them.
nullrecords the call as returned, exactly as without a classifier.- An error class records the call as failed: its
Erroris the class and itsResultis still the text the model saw. The class then goes where a thrown exception's type name goes: the claims-v3 provenance signature, the call's[failed: exit 3]marker on a laterTried:line, and the input of both the default and the model-backed reflector. - Why the naming rule. The class is stored, signed and shown to a later model, so it must be exactly the first
token the
Tried:line's classifier would find in it, at most 40 characters: a capitalised word of letters and digits ending inErrororException, orexit N. (HTTP N,status N, a POSIX errno name such asENOENT, andTimeoutare tokens too.) Anything else (blank,exit code 3,ExitCode3, a sentence, a bracket) is recorded as the fixed classExperienceCaptureOptions.ToolReportedErrorClass("ToolReportedError", shown as[failed: ToolReportedError]) and reported once per run throughOnCaptureFailureat stageToolResultClassification, with a fixed reason that never quotes the returned text. - A classifier that throws leaves the call recorded as returned and is reported once per run through
OnCaptureFailureat stageToolResultClassification: the failure'sReasonnames only the exception type, while itsExceptioncarries the exception object, as for the other host callbacks. Classifier problems have a stage of their own, so they never hide a laterToolCallreport of a call that could not be recorded. - It runs inline. It runs after the tool returned and before the result goes back to MAF and the model, so its own
time is added to every tool call: keep it fast. It is not counted in the call's recorded
Duration. It never replaces the result, and nothing it does makes the call throw. A tool that throws is recorded as before and the classifier is not called, and neither is it for a call that finishes after its run was finalized (that call is not recorded). - Threads. It runs on the tool-invocation thread and can run concurrently with itself when MAF invokes tools concurrently, so keep it fast and free of shared mutable state.
ExperienceCaptureOptions.RecipeResultExcerpt (off by default) lets the host vouch for a short excerpt of what a
working call returned, for a later agent to see on the lesson's working attempt (see
Injection; AgentExperienceOptions.Recipe sets it with the matching
allowlists):
options.Capture = capture => capture.RecipeResultExcerpt = call =>
call.ToolName == "pin_dependency" && call.Result?.ToString() is { } text && text.StartsWith("pinned ", StringComparison.Ordinal)
? text
: null;- It gets the same
ExperienceToolResultContextasClassifyToolResult, and runs only for a call capture records as returned: never for a thrown call or one the classifier named a failure. - What it returns is stored on the call as
ToolCallRecord.RecipeExcerpt, after theToolResultsanitization policy (a redacted or omitted value leaves no excerpt; one the sanitizer refuses is dropped, never the attempt) and cut toCaptureLimits.MaxRecipeExcerptLengthcharacters (200 by default) after sanitization, never between a surrogate pair. A lone surrogate becomes U+FFFD, so a host that slices its excerpt mid-pair never makes signing or the store refuse the record. A cut or a refusal is reported on the append's truncated fields. The record's payload carries the member only when it is set. - A callback that throws records no excerpt and is reported once per run through
OnCaptureFailureat stageRecipeExcerpt, naming only the exception type. - It runs inline on the tool-invocation thread, possibly concurrently with itself; keep it fast, and change nothing in its context. The arguments are the raw ones, before sanitization.
- Reusing a
ChatClientAgentRunOptionsinstance for one invocation after another is safe from 1.22.0. At 1.20.0, MAF's function middleware wrote itsChatClientFactoryonto the options instance it received, so a reused instance stacked a middleware layer per invocation. 1.22.0 works on a per-run clone and leaves the caller's instance, and any factory the host set on it, unchanged. The threeExperienceCaptureTests.A_reused_ChatClientAgentRunOptions_instance_…tests pin this for sequential reuse, streaming and not, with and without a host factory. Sharing one instance across concurrent invocations is not tested; MAF's source clones it per run, but this library makes no claim. - MAF function middleware accepts only a
nullAgentRunOptions, a plainAgentRunOptions, or aChatClientAgentRunOptions. Other options subclasses throwNotSupportedExceptionwhenCaptureToolCallsistrue. - Capture materializes the input messages once (reusing them when they are already a collection) and passes that
same collection to both
ResolveRunand the inner agent, so a one-shot sequence is not consumed by the resolver. - CI tests the range's floor and the newest 1.x on every change and on a weekly schedule, and a 1.x that breaks the
adapter fails
mainon the next push or scheduled run. MAF 2.0 and later are outside the range, and NuGet warns (NU1608) about this package when a host resolves one. The reasons are in the version policy.