Class Tryll::AgentProxy

ClassList > Tryll > AgentProxy

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

• #include <AgentProxy.h>

Public Types

Type	Name
typedef std::function< void(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 toolName, std::string_view argumentsJson)>	ToolCallCallback Callback type for tool-call notifications.
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
void	ChangeParams (std::string_view nodeName, ::Tryll::Client::NodeParamsVariant params) Blocking convenience wrapper over ChangeParamsAsync .
std::future< void >	ChangeParamsAsync (std::string_view nodeName, ::Tryll::Client::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.
std::uint64_t	GetAgentId () noexcept const Server-assigned agent identifier.
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	SetOnToolCall (ToolCallCallback cb) Register a callback for tool-call notifications.
void	SetOnTurnComplete (TurnCompleteCallback cb) Register a callback for turn-complete notifications.

Detailed Description

Public Types Documentation

typedef AnswerTextCallback

Callback type for streaming text chunks.

using Tryll::AgentProxy::AnswerTextCallback = 
std::function<void(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: * 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::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::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::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::AgentProxy::NodeEventKeyValue = std::pair<std::string, std::string>;

---

typedef ToolCallCallback

Callback type for tool-call notifications.

using Tryll::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 notify_client="true").

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 TurnCompleteCallback

Callback type for turn-complete notifications.

using Tryll::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::AgentProxy::AgentProxy () = default

---

function ChangeParams

Blocking convenience wrapper over ChangeParamsAsync .

void Tryll::AgentProxy::ChangeParams (
    std::string_view nodeName,
    ::Tryll::Client::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::AgentProxy::ChangeParamsAsync (
    std::string_view nodeName,
    ::Tryll::Client::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::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::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 GetAgentId

Server-assigned agent identifier.

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

Returns:

The agent_id field from the original CreateAgentResponse.

---

function SendText

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

void Tryll::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::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 ``(text, isDelta, isFinal), or empty to clear.

---

function SetOnError

Register a callback for agent-level error notifications.

void Tryll::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::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::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 SetOnToolCall

Register a callback for tool-call notifications.

void Tryll::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 SetOnTurnComplete

Register a callback for turn-complete notifications.

void Tryll::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.

---

---

The documentation for this class was generated from the following file C:/_tryll/_monorepo2/server/client-cpp/include/tryll/AgentProxy.h