Skip to content

Connect and Manage a Session

Open a connection to a running Tryll server, handle reconnection, and shut down cleanly.

Prerequisites

  • The Tryll server is running and reachable — see Run the Tryll Server.
  • You know the host and port (default 127.0.0.1:9100).

Steps

from tryll_client import TryllClient, TryllError, InferenceEngine

# 1. Open the socket. Blocks briefly until SessionReady arrives.
client = TryllClient.connect("127.0.0.1", 9100)

# 2. Pick the inference engine for this session.
#    Affects agents you create *after* this call.
try:
    client.configure_session(InferenceEngine.LlamaCpp)
except TryllError as e:
    print(f"configure failed: {e}")
    raise

# 3. Do your work — create storages, agents, send messages.
#    See build-chat-agent-with-graph.md for the next step.

# 4. Clean shutdown.
client.shutdown()

#include <tryll/TryllClient.h>

namespace TC = Tryll::Client;

try
{
    auto client = Tryll::TryllClient::Connect("127.0.0.1", 9100);
    client.ConfigureSession(TC::InferenceEngine::LlamaCpp);

    // ... create agents, send messages ...

    client.Shutdown();
}
catch (const Tryll::TryllError& ex)
{
    // ex.GetCode() is an ErrorCode; see reference/error-codes.md
    std::cerr << "session error " << ex.GetCode()
              << ": " << ex.what() << "\n";
}

In Blueprint: on Event BeginPlay, get the UTryllSubsystem and call Connect. Bind On Connection Changed — when bConnected = true, call Configure Session with your chosen ETryllInferenceEngine and wait for On Configure Session Complete.

In C++, the same subsystem API is available:

auto* subsystem = GetGameInstance()->GetSubsystem<UTryllSubsystem>();
subsystem->OnConnectionChanged.AddDynamic(this, &ThisClass::HandleConnection);
subsystem->Connect();

Handle reconnection

If the socket drops (server restart, network blip, etc.), the server destroys every agent and storage the session owned. The client libraries surface this as a connection-changed event or an async error:

  • Python / C++: catch the TryllError from the next request and call TryllClient.connect(...) / Tryll::TryllClient::Connect(...) again to make a fresh client. The old client's storages and agents are gone; re-create them.
  • Unreal: bind OnConnectionChanged(false) to a handler that re-calls Connect after a short delay.

There is no server-side session persistence. Everything is rebuilt from scratch on reconnect.

def reconnect() -> TryllClient:
    client = TryllClient.connect("127.0.0.1", 9100)
    client.configure_session(InferenceEngine.LlamaCpp)
    # re-create any per-session storages and agents you need
    return client

Tryll::TryllClient reconnect()
{
    auto client = Tryll::TryllClient::Connect("127.0.0.1", 9100);
    client.ConfigureSession(Tryll::Client::InferenceEngine::LlamaCpp);
    // re-create any per-session storages and agents you need
    return client;
}

// Bind OnConnectionChanged(false) to a handler that re-calls
// Connect after a short delay, then re-runs your ConfigureSession
// + graph/storage bootstrap when bConnected flips back to true.
auto* subsystem = GetGameInstance()->GetSubsystem<UTryllSubsystem>();
subsystem->Connect();

Session lifetime rules to remember

  • ConfigureSession is idempotent and can be called repeatedly. It only affects future CreateAgent calls — existing agents keep their engine.
  • String storages and embedded string storages die with the session.
  • Model downloads and loads are global, not per-session. Pinning a model in one session keeps it warm for all sessions.
  • Agent ids are session-scoped. A stored agent_id is meaningless after reconnect.

See Lifetime and Ownership for the full picture of what survives session close and what does not.

Verify it worked

Connecting and configuring produces these server-side log lines (at info level):

[info] Session 42 accepted 127.0.0.1:56102
[info] Session 42 configured engine=LlamaCpp

If you do not see a configure line, check that OnConfigureSessionComplete fired with bSuccess = true on the client. A failure is almost always a server-side inference-engine issue — see error codes 2xxx.