C++ Client API Reference¶

Full API reference for the Tryll:: C++ client library, auto-generated from Doxygen documentation blocks in server/client-cpp/include/tryll/. Browse individual classes and structs in the sidebar.

Entry points¶

Type	Role
`Tryll::TryllClient`	TCP session — connect, configure, manage models, create agents
`Tryll::ConnectedSession`	RAII pair: owns a `ManagedServer` + `TryllClient`; returned by `RunAndConnect`
`Tryll::AgentProxy`	Per-agent handle — send messages, receive streaming tokens, destroy
`Tryll::Client::GraphDescription`	Fluent graph builder — add nodes, wire routes, set start node
`Tryll::Client::ManagedServer`	RAII handle that spawns `tryll_server` and waits for TCP readiness
`Tryll::Client::ManagedServerOptions`	Configuration for `ManagedServer::Start`
`Tryll::MessageResult`	Streaming result handle returned by synchronous `SendMessage`
`Tryll::TryllError`	Error type carrying a numeric code and human-readable message

Supporting types¶

Type	Role
`Tryll::Client::SessionConfig`	All session-configuration options, passed to `ConfigureSession`
`Tryll::Client::GraphDescription::NodeDesc`	Single node description inside a graph
`Tryll::Client::GraphDescription::RouteDesc`	Single exit-route wire inside a graph
`Tryll::ModelInfoT`	Model catalog entry returned by `ListModels` (FlatBuffers object-API type)
`Tryll::Client::ToolDef`	Tool declaration passed on `CreateAgentRequest`
`Tryll::Client::ToolParamDef`	Single parameter within a `ToolDef`
`Tryll::TryllClient::EmbeddedStorageInfo`	Embedded-storage descriptor returned by `ListEmbeddedStorages`

Selected method signatures¶

`TryllClient::ConfigureSession`¶

struct SessionConfig
{
    ::Tryll::InferenceEngine   engine          = ::Tryll::InferenceEngine_Mock;
    ::Tryll::InferenceEngine   sttEngine       = ::Tryll::InferenceEngine_Mock;
    ::Tryll::InferenceEngine   ttsEngine       = ::Tryll::InferenceEngine_Mock;
    ::Tryll::InferenceEngine   embeddingEngine = ::Tryll::InferenceEngine_Mock;
    bool                       allowAutoModelDownloading = false;
    std::string                gameName;
    std::chrono::milliseconds  timeout = std::chrono::seconds(30);
};

void ConfigureSession(const SessionConfig& cfg);

Each *Engine field selects the inference backend for that model kind independently. Engines default to InferenceEngine_Mock — set only the ones your session uses:

// Language-only session (most common)
client.ConfigureSession({ .engine = ::Tryll::InferenceEngine_LlamaCpp });

// Language + STT (voice input)
client.ConfigureSession({
    .engine    = ::Tryll::InferenceEngine_LlamaCpp,
    .sttEngine = ::Tryll::InferenceEngine_SherpaOnnx,
});

When allowAutoModelDownloading is true, subsequent CreateAgent calls will automatically download any missing models referenced by the graph. The default CreateAgent timeout is automatically extended to 30 minutes when this flag is active. See Enable Auto Model Downloading.

`AgentProxy` callbacks¶

All callbacks are registered on an AgentProxy instance before sending the first message. They fire on the reader thread — they must return quickly and must not call any blocking TryllClient or AgentProxy methods.

Dispatch priority: typed callbacks (SetOnToolCall, SetOnIntentClassified) take precedence. If no typed callback is registered for an incoming NodeEvent, the SetOnNodeEvent fallback fires instead.

Method	Callback type	Fires when
`SetOnAnswerText(cb)`	`void(string_view text, bool isDelta, bool isFinal)`	Each `AnswerText` frame during a turn.
`SetOnTurnComplete(cb)`	`void(TurnStatus status, string_view debugInfoJson, int32_t tokensGenerated)`	`TurnComplete` arrives.
`SetOnError(cb)`	`void(const TryllError& error)`	Server-reported error or disconnect mid-turn. Does not fire for `TurnStatus_Error` turns (those arrive via `SetOnTurnComplete`).
`SetOnToolCall(cb)`	`void(string_view toolName, string_view argumentsJson)`	`NodeEvent` with `event_type="tool_call"` (requires `notify_client="true"` on the `ToolCall` node).
`SetOnIntentClassified(cb)`	`void(string_view intent, string_view recordId, size_t recordIndex, float distance)`	`NodeEvent` with `event_type="intent_classified"` (requires `notify_client="true"` on a `ClassifyIntent` node).
`SetOnNodeEvent(cb)`	`void(string_view nodeName, string_view eventType, const vector<NodeEventKeyValue>& kvPairs)`	Any `NodeEvent` whose `event_type` is unrecognised or whose typed callback is not set.

Pass a default-constructed std::function to unregister a callback.

// Register callbacks before the first SendText / SendMessage call.
agent.SetOnAnswerText([&](std::string_view text, bool, bool isFinal) {
    std::cout << text;
    if (isFinal) std::cout << '\n';
});

agent.SetOnIntentClassified([&](std::string_view intent,
                                std::string_view recordId,
                                std::size_t      recordIndex,
                                float            distance) {
    std::cout << "Intent: " << intent
              << " (record " << recordId
              << ", dist " << distance << ")\n";
});

// Generic fallback for any other NodeEvent types.
agent.SetOnNodeEvent([](std::string_view nodeName,
                        std::string_view eventType,
                        const std::vector<Tryll::AgentProxy::NodeEventKeyValue>& kv) {
    std::cout << "[NodeEvent] " << nodeName << " / " << eventType << '\n';
    for (auto& [k, v] : kv)
        std::cout << "  " << k << "=" << v << '\n';
});

See the AgentProxy Doxygen page for the full documentation of each callback type.

Headers¶

Header	Declares
`tryll/TryllClient.h`	`TryllClient`, `ConnectedSession`, session-level types
`tryll/AgentProxy.h`	`AgentProxy` and all callback types
`tryll/GraphDescription.h`	`GraphDescription` and its nested types
`tryll/ManagedServer.h`	`ManagedServer`, `ManagedServerOptions`
`tryll/MessageResult.h`	`MessageResult`
`tryll/TryllError.h`	`TryllError`