Class ClaudeAgent

Namespace

Emissary

Assembly

Emissary.dll

The agent loop: sends the conversation to Claude, streams the response, executes requested tools (in parallel), feeds results back, and repeats until the model finishes or a limit hits.

public sealed class ClaudeAgent

Inheritance

object

ClaudeAgent

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

ClaudeAgent(AgentOptions)

Creates an agent talking to the Claude API.

public ClaudeAgent(AgentOptions options)

Parameters

options AgentOptions

The agent configuration.

ClaudeAgent(AgentOptions, Trajectory, ToolReplayMode)

Creates an agent that replays a recorded trajectory instead of calling the API.

public ClaudeAgent(AgentOptions options, Trajectory trajectory, ToolReplayMode toolReplay = ToolReplayMode.Execute)

Parameters

options AgentOptions

The agent configuration; must match the recorded run.

trajectory Trajectory

The recording to replay.

toolReplay ToolReplayMode

Whether tools execute for real or serve their recorded results. Defaults to executing, which is what replay has always done; FromRecording makes the replay hermetic, so a run whose tools touch a database replays without one.

Exceptions

TrajectoryDivergenceException

Thrown during a run if it diverges from the recording.

ClaudeAgent(AgentOptions, TrajectoryRecorder)

Creates an agent talking to the Claude API, recording every exchange.

public ClaudeAgent(AgentOptions options, TrajectoryRecorder recorder)

Parameters

options AgentOptions

The agent configuration.

recorder TrajectoryRecorder

Receives every completed model exchange.

Methods

AsTool(string, string)

Exposes this whole agent as a single tool for another agent — the composition primitive for sub-agent hierarchies. The tool takes a message and returns the sub-agent's final answer. Safety composes conservatively: the tool is marked Untrusted if this agent can read untrusted content, and Privileged if it can perform privileged effects — so a parent's taint tracking and contracts see through the boundary.

public ToolDefinition AsTool(string name, string description)

Parameters

name string

The wire name of the composed tool.

description string

The description shown to the parent's model.

Returns

ToolDefinition

CompensateAsync(AgentResult, CancellationToken)

Undoes the effects of a completed run (saga compensation): every successfully executed tool with a Compensation handler is compensated with its original input, in reverse call order. Shadow-planned effects were never executed and are skipped.

public Task<IReadOnlyList<CompensationResult>> CompensateAsync(AgentResult result, CancellationToken cancellationToken = default)

Parameters

result AgentResult

The run to unwind.

cancellationToken CancellationToken

Cancels the compensation pass.

Returns

Task<IReadOnlyList<CompensationResult>>

ResumeAsync(SuspendedRun, bool, CancellationToken)

Resumes a suspended run with a human decision and returns the outcome.

public Task<AgentResult> ResumeAsync(SuspendedRun run, bool approve, CancellationToken cancellationToken = default)

Parameters

run SuspendedRun

The suspension state (from Suspension or a store).

approve bool

Whether the gated calls may execute; denial informs the model instead.

cancellationToken CancellationToken

Cancels the run.

Returns

Task<AgentResult>

ResumeStreamAsync(SuspendedRun, bool, CancellationToken)

Resumes a suspended run with a human decision, streaming events as they happen.

public IAsyncEnumerable<AgentEvent> ResumeStreamAsync(SuspendedRun run, bool approve, CancellationToken cancellationToken = default)

Parameters

run SuspendedRun

The suspension state (from Suspension or a store).

approve bool

Whether the gated calls may execute; denial informs the model instead.

cancellationToken CancellationToken

Cancels the run.

Returns

IAsyncEnumerable<AgentEvent>

RunAsync(Conversation, CancellationToken)

Runs the agent on an existing conversation and returns the outcome.

public Task<AgentResult> RunAsync(Conversation conversation, CancellationToken cancellationToken = default)

Parameters

conversation Conversation

The conversation so far; the last message must be from the user.

cancellationToken CancellationToken

Cancels the run.

Returns

Task<AgentResult>

RunAsync(string, CancellationToken)

Runs the agent on a single user message and returns the outcome.

public Task<AgentResult> RunAsync(string userInput, CancellationToken cancellationToken = default)

Parameters

userInput string

The user's text.

cancellationToken CancellationToken

Cancels the run.

Returns

Task<AgentResult>

RunAsync<T>(string, JsonTypeInfo<T>, CancellationToken)

Runs the agent and deserializes the final answer as T — pair with WithOutput<T>() so the answer is schema-guaranteed.

public Task<T> RunAsync<T>(string userInput, JsonTypeInfo<T> typeInfo, CancellationToken cancellationToken = default)

Parameters

userInput string

The user's text.

typeInfo JsonTypeInfo<T>

Source-generated serializer metadata for T.

cancellationToken CancellationToken

Cancels the run.

Returns

Task<T>

Type Parameters

T

The structured output type.

StreamAsync(Conversation, CancellationToken)

Runs the agent on an existing conversation, streaming events as they happen.

public IAsyncEnumerable<AgentEvent> StreamAsync(Conversation conversation, CancellationToken cancellationToken = default)

Parameters

conversation Conversation

The conversation so far; the last message must be from the user.

cancellationToken CancellationToken

Cancels the run.

Returns

IAsyncEnumerable<AgentEvent>

StreamAsync(string, CancellationToken)

Runs the agent on a single user message, streaming events as they happen.

public IAsyncEnumerable<AgentEvent> StreamAsync(string userInput, CancellationToken cancellationToken = default)

Parameters

userInput string

The user's text.

cancellationToken CancellationToken

Cancels the run.

Returns

IAsyncEnumerable<AgentEvent>

StreamAsync<T>(string, JsonTypeInfo<T>, CancellationToken)

Streams a structured answer as it is generated: each item is the best-known partial value, filled in further with every chunk, and the last item is the complete answer. Pair with WithOutput<T>() so the model is constrained to the schema.

public IAsyncEnumerable<T> StreamAsync<T>(string userInput, JsonTypeInfo<T> typeInfo, CancellationToken cancellationToken = default)

Parameters

userInput string

The user's text.

typeInfo JsonTypeInfo<T>

Source-generated serializer metadata for T.

cancellationToken CancellationToken

Cancels the run.

Returns

IAsyncEnumerable<T>

Type Parameters

T

The structured output type.

Remarks

Chunks that do not yet form a deserializable value — a half-written property name, a partially spelled enum — are skipped rather than surfaced, so every item you receive is a deserializable T.

A partial is a progress snapshot, not a validated value. Properties that have not arrived yet are null or default even when the type declares them non-nullable, and a string property may hold only the part received so far. Guard against nulls when rendering partials, and use the final item (or RunAsync<T>(string, JsonTypeInfo<T>, CancellationToken)) when you need the whole answer.