Skip to content

Class Tryll::Client::AgentProxy

ClassList > Tryll > Client > AgentProxy

Client-side handle for one server-side agent. More...

  • #include <AgentProxy.h>

Classes

Type Name
struct DialogInteraction
struct ToolCallEvent
Owning tool-call event for deferred / async handling.
struct ToolResult
One model-visible result correlated to a tool_call event's call_id.

Public Types

Type Name
typedef std::function< void(std::string_view nodeName, std::string_view text, bool isDelta, bool isFinal)> AnswerTextCallback
Callback type for streaming text chunks.
typedef std::function< void(const TryllError &error)> ErrorCallback
Callback type for agent-level error notifications.
typedef std::function< void(std::string_view intent, std::string_view recordId, std::size_t recordIndex, float distance)> IntentClassifiedCallback
Callback type for intent-classification notifications.
typedef std::function< void(std::string_view nodeName, std::string_view eventType, const std::vector< NodeEventKeyValue > &kvPairs)> NodeEventCallback
Generic NodeEvent callback.
typedef std::pair< std::string, std::string > NodeEventKeyValue
One ordered key/value pair in a NodeEvent payload.
typedef std::function< void(std::string_view nodeName, std::string_view pendingExit)> PausedCallback
Callback type for pause notifications.
typedef std::function< void(std::string_view toolName, std::string_view argumentsJson)> ToolCallCallback
Callback type for tool-call notifications.
typedef std::function< void(const ToolCallEvent &event)> ToolCallEventCallback
Preferred tool-call callback with owning payload.
typedef std::function< void(std::string_view callId, std::string_view toolName, std::string_view argumentsJson)> ToolCallWithIdCallback
Call-ID-aware tool-call callback.
typedef std::function< void(std::string_view nodeName, std::span< const int16_t > pcm)> TtsAudioCallback
Callback type for streaming TTS PCM chunks.
typedef std::function< void(std::string_view nodeName, uint32_t sampleRate, uint16_t channels, uint16_t bitsPerSample)> TtsAudioFormatCallback
Callback type for the TTS audio format announcement.
typedef std::function< void(::Tryll::TurnStatus status, std::string_view debugInfoJson, std::int32_t tokensGenerated)> TurnCompleteCallback
Callback type for turn-complete notifications.

Public Functions

Type Name
AgentProxy () = default
std::uint32_t AppendInteractions (std::span< const DialogInteraction > interactions)
Blocking convenience wrapper over AppendInteractionsAsync .
std::future< std::uint32_t > AppendInteractionsAsync (std::span< const DialogInteraction > interactions)
void Cancel (::Tryll::CancelMode mode=::Tryll::CancelMode_StopAndKeep)
Cooperatively cancel the in-flight turn (fire-and-forget).
void ChangeParams (std::string_view nodeName, NodeParamsVariant params)
Blocking convenience wrapper over ChangeParamsAsync .
std::future< void > ChangeParamsAsync (std::string_view nodeName, NodeParamsVariant params)
Apply typed node parameters to a named workflow node asynchronously.
void Destroy ()
Blocking convenience wrapper over DestroyAsync .
std::future< void > DestroyAsync ()
Request agent destruction on the server asynchronously.
AgentKvCacheEvictResult EvictKvCache ()
Blocking convenience wrapper over EvictKvCacheAsync .
std::future< AgentKvCacheEvictResult > EvictKvCacheAsync ()
Release raw eligible language-model contexts while retaining agent state.
std::uint64_t GetAgentId () noexcept const
Server-assigned agent identifier.
AgentKvCacheStatus GetKvCacheStatus ()
Blocking convenience wrapper over GetKvCacheStatusAsync .
std::future< AgentKvCacheStatus > GetKvCacheStatusAsync ()
Return aggregate KV-cache lifecycle state for this agent.
AgentKvCachePrefillResult PrefillKvCache ()
Blocking convenience wrapper over PrefillKvCacheAsync .
std::future< AgentKvCachePrefillResult > PrefillKvCacheAsync ()
Synchronise eligible language-model contexts to the reusable prefix.
std::uint32_t RemoveInteractionsFromEnd (std::uint32_t count)
Blocking convenience wrapper over RemoveInteractionsFromEndAsync .
std::future< std::uint32_t > RemoveInteractionsFromEndAsync (std::uint32_t count)
void Resume (std::string_view resumeNode={})
Blocking convenience wrapper over ResumeAsync .
std::future< void > ResumeAsync (std::string_view resumeNode={})
Resume a turn that is currently paused (see SetOnPaused ).
void ResumeWithToolResult (const ToolResult & toolResult, std::string_view resumeNode={})
Blocking convenience wrapper over ResumeWithToolResultAsync .
std::future< void > ResumeWithToolResultAsync (const ToolResult & toolResult, std::string_view resumeNode={})
Resume with one correlated tool result.
void ResumeWithToolResults (std::span< const ToolResult > toolResults, std::string_view resumeNode={})
Blocking convenience wrapper over ResumeWithToolResultsAsync .
std::future< void > ResumeWithToolResultsAsync (std::span< const ToolResult > toolResults, std::string_view resumeNode={})
Resume with the complete result batch for one paused tool-call pass.
void SendText (std::string_view text)
Send a text message to the agent (fire-and-forget).
void SetOnAnswerText (AnswerTextCallback cb)
Register a callback for streaming text chunks.
void SetOnError (ErrorCallback cb)
Register a callback for agent-level error notifications.
void SetOnIntentClassified (IntentClassifiedCallback cb)
Register a callback for intent-classification notifications.
void SetOnNodeEvent (NodeEventCallback cb)
Register a generic NodeEvent fallback callback.
void SetOnPaused (PausedCallback cb)
Register a callback for pause notifications.
void SetOnToolCall (ToolCallCallback cb)
Register a callback for tool-call notifications.
void SetOnToolCallEvent (ToolCallEventCallback cb)
Register the preferred owning tool-call callback.
void SetOnToolCallWithId (ToolCallWithIdCallback cb)
Register a call-ID-aware tool-call callback.
void SetOnTtsAudio (TtsAudioCallback cb)
Register (or clear) the TTS audio chunk callback.
void SetOnTtsAudioFormat (TtsAudioFormatCallback cb)
Register (or clear) the TTS audio format callback.
void SetOnTurnComplete (TurnCompleteCallback cb)
Register a callback for turn-complete notifications.
AgentVariables & Variables ()
The agent's declared variables (mirror + deferred-flush batcher).

Detailed Description

Public Types Documentation

typedef AnswerTextCallback

Callback type for streaming text chunks.

using Tryll::Client::AgentProxy::AnswerTextCallback = std::function<
       void(std::string_view nodeName, std::string_view text, bool isDelta, bool isFinal)>;

Invoked on the reader thread for each AnswerText frame received from the server (including frames from server-initiated turns such as voice autosend). Must return quickly and must not call any blocking TryllClient or AgentProxy methods.

Parameters: * nodeName — name of the workflow node that produced this text (multi-sender attribution; e.g. distinguishing two Generate nodes voicing different characters in the same turn). * text — streamed text chunk. * isDelta — true when text is an incremental token/chunk; false when it is the accumulated response so far. * isFinal — true for the last chunk before TurnComplete.


typedef ErrorCallback

Callback type for agent-level error notifications.

using Tryll::Client::AgentProxy::ErrorCallback = std::function<void(const TryllError& error)>;

Invoked on the reader thread when a SendText turn is terminated by a server-reported ErrorResponse, or when the connection drops mid-turn. Must return quickly and must not call any blocking methods.

Parameters:

  • error The error reported by the server or transport layer.

typedef IntentClassifiedCallback

Callback type for intent-classification notifications.

using Tryll::Client::AgentProxy::IntentClassifiedCallback = 
std::function<void(std::string_view intent,
                   std::string_view recordId,
                   std::size_t      recordIndex,
                   float            distance)>;

Invoked on the reader thread for each NodeEvent with event_type="intent_classified" — fired by ClassifyIntentNode on its "found" path when notify_client="true".

Parameters: * intent — the classified intent label. * recordId — id of the top-1 matched KB record. * recordIndex — 0-based index of the matched record in storage. * distance — cosine distance of the match.

Must return quickly and must not call any blocking methods.


typedef NodeEventCallback

Generic NodeEvent callback.

using Tryll::Client::AgentProxy::NodeEventCallback = 
std::function<void(std::string_view nodeName,
                   std::string_view eventType,
                   const std::vector<NodeEventKeyValue>& kvPairs)>;

Invoked on the reader thread when a NodeEvent arrives whose event_type is unrecognised or whose typed callback is not set. If a typed callback (e.g. ToolCallCallback, IntentClassifiedCallback) is registered for the incoming event_type, this callback is NOT fired for that event.

Parameters: * nodeName — name of the emitting workflow node. * eventType — event discriminator. * kvPairs — ordered string→string payload.


typedef NodeEventKeyValue

One ordered key/value pair in a NodeEvent payload.

using Tryll::Client::AgentProxy::NodeEventKeyValue = std::pair<std::string, std::string>;


typedef PausedCallback

Callback type for pause notifications.

using Tryll::Client::AgentProxy::PausedCallback = 
std::function<void(std::string_view nodeName, std::string_view pendingExit)>;

Invoked on the reader thread for each NodeEvent with event_type="paused" — fired by the executor when it pauses the turn between nodes (see PauseNode, pausing ToolCallDisposition values).

Parameters: * nodeName — the node that just exited and triggered the pause. * pendingExit — the exit route that will be taken on a plain (non-jump) Resume.

Must return quickly and must not call any blocking methods.


typedef ToolCallCallback

Callback type for tool-call notifications.

using Tryll::Client::AgentProxy::ToolCallCallback = 
std::function<void(std::string_view toolName, std::string_view argumentsJson)>;

Invoked on the reader thread for each NodeEvent with event_type="tool_call" received from the server (i.e. when the agent's graph has a ToolCall node with a notifying disposition).

Parameters: * toolName — the tool the model asked to call. * argumentsJson — compact JSON object of arguments, e.g. {"city":"Berlin"}.

Must return quickly and must not call any blocking methods.


typedef ToolCallEventCallback

Preferred tool-call callback with owning payload.

using Tryll::Client::AgentProxy::ToolCallEventCallback = std::function<void(const ToolCallEvent& event)>;

Invoked on the reader thread. Must return quickly and must not call blocking client methods; use ResumeWithToolResultsAsync instead.


typedef ToolCallWithIdCallback

Call-ID-aware tool-call callback.

using Tryll::Client::AgentProxy::ToolCallWithIdCallback = 
std::function<void(std::string_view callId,
                   std::string_view toolName,
                   std::string_view argumentsJson)>;

This is the result-bearing counterpart to ToolCallCallback. The callId must be echoed in a ToolResult passed to ResumeWithToolResult or ResumeWithToolResults.


typedef TtsAudioCallback

Callback type for streaming TTS PCM chunks.

using Tryll::Client::AgentProxy::TtsAudioCallback = 
std::function<void(std::string_view nodeName, std::span<const int16_t> pcm)>;

Fired for each int16 LE PCM chunk synthesized by a GenerateAndSpeak/Speak node. End-of-stream is signalled by the existing turn-complete future returned from SendMessage — there is no per-chunk final flag.

Parameters: * nodeName — name of the producing node (multi-sender attribution). * pcm — the PCM chunk.

Must return quickly and must not call any blocking methods.


typedef TtsAudioFormatCallback

Callback type for the TTS audio format announcement.

using Tryll::Client::AgentProxy::TtsAudioFormatCallback = 
std::function<void(std::string_view nodeName, uint32_t sampleRate, uint16_t channels, uint16_t bitsPerSample)>;

Fired once per GenerateAndSpeak/Speak turn, before the first TtsAudioFrame.

Parameters: * nodeName — name of the producing node (multi-sender attribution). * sampleRate — PCM sample rate (e.g. 22050). * channels — channel count (always 1 for current models). * bitsPerSample — bit depth (always 16).


typedef TurnCompleteCallback

Callback type for turn-complete notifications.

using Tryll::Client::AgentProxy::TurnCompleteCallback = 
std::function<void(::Tryll::TurnStatus status,
                   std::string_view debugInfoJson,
                   std::int32_t tokensGenerated)>;

Invoked on the reader thread once per turn, immediately after TurnComplete arrives. Covers both client-initiated turns (via SendText) and server-initiated turns (voice autosend).

Parameters: * status — turn outcome (::Tryll::TurnStatus). * debugInfoJson — JSON diagnostics string; non-empty only when the agent was created with enableDiagnostics=true. * tokensGenerated — total tokens sampled across all generation nodes.

Must return quickly and must not call any blocking methods.


Public Functions Documentation

function AgentProxy [1/2]

Tryll::Client::AgentProxy::AgentProxy () = default

function AppendInteractions

Blocking convenience wrapper over AppendInteractionsAsync .

std::uint32_t Tryll::Client::AgentProxy::AppendInteractions (
    std::span< const DialogInteraction > interactions
) 


function AppendInteractionsAsync

std::future< std::uint32_t > Tryll::Client::AgentProxy::AppendInteractionsAsync (
    std::span< const DialogInteraction > interactions
) 

Append scripted interactions without running the graph. Idle-only.

Returns:

Number of interactions actually appended.


function Cancel

Cooperatively cancel the in-flight turn (fire-and-forget).

void Tryll::Client::AgentProxy::Cancel (
    ::Tryll::CancelMode mode=::Tryll::CancelMode_StopAndKeep
) 

Stops generation; the active SendText turn ends with TurnStatus::Cancelled through SetOnTurnComplete. No-op if the agent is idle. mode selects whether the partial interaction is kept (default) or discarded as if the turn never happened.

Parameters:

  • mode Cancel disposition (StopAndKeep / StopAndDiscard).

function ChangeParams

Blocking convenience wrapper over ChangeParamsAsync .

void Tryll::Client::AgentProxy::ChangeParams (
    std::string_view nodeName,
    NodeParamsVariant params
) 

Exception:

  • TryllError On server-reported errors or disconnect.

function ChangeParamsAsync

Apply typed node parameters to a named workflow node asynchronously.

std::future< void > Tryll::Client::AgentProxy::ChangeParamsAsync (
    std::string_view nodeName,
    NodeParamsVariant params
) 

The supplied params must match the concrete type of the target node (type mismatch → InvalidParamValue 3007 from the server). The mutation diff-loop on the server vetoes structural fields and invokes OnXxxChanged callbacks for fields that have changed.

The C++ client does not cache a baseline copy of authored params: callers must own the typed params they last sent (or authored at CreateAgent) and start each mutation from that local copy. Structural fields must match the create-time values or the server returns ParamNotMutable.

Typical clone-set-send idiom:

GenerateParamsT p = myBaseline;   // caller-owned copy of authored params
p.system_prompt    = "New system prompt";
agent.ChangeParams("gen", std::move(p));

Parameters:

  • nodeName Instance name of the target node (as declared in the graph).
  • params Whole authored typed params for the node.

Returns:

Future completing on Ack. Throws TryllError on server-reported errors (UnknownNode 3005, ParamNotMutable 3006, InvalidParamValue 3007, or AgentBusy 3004).


function Destroy

Blocking convenience wrapper over DestroyAsync .

void Tryll::Client::AgentProxy::Destroy () 

Exception:

  • TryllError On server-reported errors, disconnect, or timeout (configured by the owning client).

function DestroyAsync

Request agent destruction on the server asynchronously.

std::future< void > Tryll::Client::AgentProxy::DestroyAsync () 

All registered callbacks are cleared before the destroy request is sent. The proxy becomes inert once the returned future completes; further SendText calls are no-ops.

Returns:

Future completing when the server acknowledges destruction.


function EvictKvCache

Blocking convenience wrapper over EvictKvCacheAsync .

AgentKvCacheEvictResult Tryll::Client::AgentProxy::EvictKvCache () 


function EvictKvCacheAsync

Release raw eligible language-model contexts while retaining agent state.

std::future< AgentKvCacheEvictResult > Tryll::Client::AgentProxy::EvictKvCacheAsync () 


function GetAgentId

Server-assigned agent identifier.

inline std::uint64_t Tryll::Client::AgentProxy::GetAgentId () noexcept const

Returns:

The agent_id field from the original CreateAgentResponse.


function GetKvCacheStatus

Blocking convenience wrapper over GetKvCacheStatusAsync .

AgentKvCacheStatus Tryll::Client::AgentProxy::GetKvCacheStatus () 


function GetKvCacheStatusAsync

Return aggregate KV-cache lifecycle state for this agent.

std::future< AgentKvCacheStatus > Tryll::Client::AgentProxy::GetKvCacheStatusAsync () 


function PrefillKvCache

Blocking convenience wrapper over PrefillKvCacheAsync .

AgentKvCachePrefillResult Tryll::Client::AgentProxy::PrefillKvCache () 


function PrefillKvCacheAsync

Synchronise eligible language-model contexts to the reusable prefix.

std::future< AgentKvCachePrefillResult > Tryll::Client::AgentProxy::PrefillKvCacheAsync () 


function RemoveInteractionsFromEnd

Blocking convenience wrapper over RemoveInteractionsFromEndAsync .

std::uint32_t Tryll::Client::AgentProxy::RemoveInteractionsFromEnd (
    std::uint32_t count
) 


function RemoveInteractionsFromEndAsync

std::future< std::uint32_t > Tryll::Client::AgentProxy::RemoveInteractionsFromEndAsync (
    std::uint32_t count
) 

Remove whole interactions from the end of the dialog. Idle-only. count=0 no-op; count>=size clears all.

Returns:

Number actually removed.


function Resume

Blocking convenience wrapper over ResumeAsync .

void Tryll::Client::AgentProxy::Resume (
    std::string_view resumeNode={}
) 

Exception:

  • TryllError On server-reported errors or disconnect.

function ResumeAsync

Resume a turn that is currently paused (see SetOnPaused ).

std::future< void > Tryll::Client::AgentProxy::ResumeAsync (
    std::string_view resumeNode={}
) 

Parameters:

  • resumeNode Empty continues via the paused node's pending exit route; non-empty jumps to that node by name.

Returns:

Future completing on Ack. Throws TryllError on server-reported errors (AgentNotPaused 3012 if the agent is not currently paused, UnknownNode 3005 if resumeNode does not name a node in the graph).


function ResumeWithToolResult

Blocking convenience wrapper over ResumeWithToolResultAsync .

void Tryll::Client::AgentProxy::ResumeWithToolResult (
    const ToolResult & toolResult,
    std::string_view resumeNode={}
) 


function ResumeWithToolResultAsync

Resume with one correlated tool result.

std::future< void > Tryll::Client::AgentProxy::ResumeWithToolResultAsync (
    const ToolResult & toolResult,
    std::string_view resumeNode={}
) 


function ResumeWithToolResults

Blocking convenience wrapper over ResumeWithToolResultsAsync .

void Tryll::Client::AgentProxy::ResumeWithToolResults (
    std::span< const ToolResult > toolResults,
    std::string_view resumeNode={}
) 


function ResumeWithToolResultsAsync

Resume with the complete result batch for one paused tool-call pass.

std::future< void > Tryll::Client::AgentProxy::ResumeWithToolResultsAsync (
    std::span< const ToolResult > toolResults,
    std::string_view resumeNode={}
) 


function SendText

Send a text message to the agent (fire-and-forget).

void Tryll::Client::AgentProxy::SendText (
    std::string_view text
) 

Enqueues the message and returns immediately. The response arrives through the persistent callbacks registered via SetOnAnswerText, SetOnTurnComplete, and SetOnError. Register those callbacks before the first SendText call.

Parameters:

  • text User-turn text to send.

function SetOnAnswerText

Register a callback for streaming text chunks.

void Tryll::Client::AgentProxy::SetOnAnswerText (
    AnswerTextCallback cb
) 

Replaces any previously set callback. Pass an empty (default- constructed) AnswerTextCallback to unregister.

Fires on the reader thread for every AnswerText frame, including frames from server-initiated turns (e.g. voice autosend).

Parameters:

  • cb Callable invoked with ``(nodeName, text, isDelta, isFinal), or empty to clear.

function SetOnError

Register a callback for agent-level error notifications.

void Tryll::Client::AgentProxy::SetOnError (
    ErrorCallback cb
) 

Replaces any previously set callback. Pass an empty (default- constructed) ErrorCallback to unregister.

Fires on the reader thread when a SendText turn is terminated by a server-reported error or a connection drop. Does not fire for ::Tryll::TurnStatus_Error turns (those arrive via SetOnTurnComplete).

Parameters:

  • cb Callable invoked with the TryllError, or empty to clear.

function SetOnIntentClassified

Register a callback for intent-classification notifications.

void Tryll::Client::AgentProxy::SetOnIntentClassified (
    IntentClassifiedCallback cb
) 

Replaces any previously set callback. Pass an empty (default- constructed) IntentClassifiedCallback to unregister.

Fires on the reader thread for every NodeEvent with event_type="intent_classified" the server sends for this agent (emitted by ClassifyIntentNode when notify_client="true").

Parameters:

  • cb Callable invoked with ``(intent, recordId, recordIndex, distance), or empty to clear.

function SetOnNodeEvent

Register a generic NodeEvent fallback callback.

void Tryll::Client::AgentProxy::SetOnNodeEvent (
    NodeEventCallback cb
) 

Replaces any previously set callback. Pass an empty (default-constructed) NodeEventCallback to unregister.

Fires on the reader thread for every NodeEvent whose event_type is either unrecognised or has no typed callback registered. When a typed callback handles the event, this one is NOT invoked for the same event.

Parameters:

  • cb Callable invoked with ``(nodeName, eventType, kvPairs), or empty to clear.

function SetOnPaused

Register a callback for pause notifications.

void Tryll::Client::AgentProxy::SetOnPaused (
    PausedCallback cb
) 

Replaces any previously set callback. Pass an empty (default- constructed) PausedCallback to unregister.

Fires on the reader thread for every NodeEvent with event_type="paused" the server sends for this agent.

Parameters:

  • cb Callable invoked with ``(nodeName, pendingExit), or empty to clear.

function SetOnToolCall

Register a callback for tool-call notifications.

void Tryll::Client::AgentProxy::SetOnToolCall (
    ToolCallCallback cb
) 

Replaces any previously set callback. Pass an empty (default- constructed) ToolCallCallback to unregister.

Fires on the reader thread for every NodeEvent with event_type="tool_call" the server sends for this agent.

Parameters:

  • cb Callable invoked with ``(toolName, argumentsJson), or empty to clear.

function SetOnToolCallEvent

Register the preferred owning tool-call callback.

void Tryll::Client::AgentProxy::SetOnToolCallEvent (
    ToolCallEventCallback cb
) 

Invoked in addition to any legacy SetOnToolCall / SetOnToolCallWithId callbacks. Pass an empty callback to unregister.

Warning:

The legacy string_view callbacks receive views into the inbound frame buffer that are valid only for the duration of the synchronous callback. Use this API when capturing fields for deferred work.


function SetOnToolCallWithId

Register a call-ID-aware tool-call callback.

void Tryll::Client::AgentProxy::SetOnToolCallWithId (
    ToolCallWithIdCallback cb
) 

The legacy SetOnToolCall callback remains supported and is also invoked when registered. Pass an empty callback to unregister.


function SetOnTtsAudio

Register (or clear) the TTS audio chunk callback.

void Tryll::Client::AgentProxy::SetOnTtsAudio (
    TtsAudioCallback cb
) 


function SetOnTtsAudioFormat

Register (or clear) the TTS audio format callback.

void Tryll::Client::AgentProxy::SetOnTtsAudioFormat (
    TtsAudioFormatCallback cb
) 


function SetOnTurnComplete

Register a callback for turn-complete notifications.

void Tryll::Client::AgentProxy::SetOnTurnComplete (
    TurnCompleteCallback cb
) 

Replaces any previously set callback. Pass an empty (default- constructed) TurnCompleteCallback to unregister.

Fires on the reader thread once per TurnComplete frame, for both client-initiated and server-initiated turns.

Parameters:

  • cb Callable invoked with ``(status, debugInfoJson, tokensGenerated), or empty to clear.

function Variables

The agent's declared variables (mirror + deferred-flush batcher).

AgentVariables & Tryll::Client::AgentProxy::Variables () 

See Tryll::Client::AgentVariables. Writes staged here are flushed automatically as one batched request immediately before the next SendText / Resume / ResumeAsync / ChangeParams / ChangeParamsAsync call (not Cancel) — see docs/research/workflow/per-agent-variables-requirements.md §6.3.

Returns:

Reference to the mirror, valid for the lifetime of the underlying client connection.


Friends Documentation

friend TryllClientImpl

class Tryll::Client::AgentProxy::TryllClientImpl (
    Internal::TryllClientImpl
) 


The documentation for this class was generated from the following file C:/_tryll/_monorepo3/tryll/clients/cpp/include/tryll/AgentProxy.h