Unity Client API¶

Package: com.tryll.client
Namespace: Tryll.Client
Target: Unity 6 (6000.x), .NET Standard 2.1, Windows Standalone + Editor

The Unity client is a hand-authored C# port of the Unreal plugin. The public surface is documented on this page; internal types under Tryll.Client.Internal are not part of the public API.

TryllClient¶

Singleton MonoBehaviour. Created automatically by TryllClientModule via [RuntimeInitializeOnLoadMethod(BeforeSceneLoad)].

public static TryllClient Instance { get; }
public bool  IsConnected { get; }
public ulong SessionId   { get; }

public string ServerHost;  // default "127.0.0.1"
public int    ServerPort;  // default 9100

// Connection
public void Connect();
public void Disconnect();

// Session
public void ConfigureSession(TryllInferenceEngine engine,
                             bool allowAutoModelDownloading = false);

// Agent lifecycle — always check error.IsOk before using the agent
public Task<(TryllAgent agent, TryllError error)>
    RequestCreateAgentAsync(TryllGraphDescription graph, bool enableDiagnostics = false);

// Model management
public Task<(List<TryllModelInfo> models, TryllError error)> RequestListModelsAsync();
public void RequestDownloadModel(string modelName);
public void RequestLoadModel(string modelName);
public void RequestUnloadModel(string modelName);

// StringStorage
public Task<TryllError> RequestCreateStringStorageAsync(string name, List<string> strings);
public Task<TryllError> RequestCreateStringStorageFromFileAsync(string name, string filePath);
public Task<TryllError> RequestDestroyStringStorageAsync(string name);

// EmbeddedStringStorage (RAG)
public Task<(EmbeddedStorageInfo info, TryllError error)>
    RequestCreateEmbeddedStringStorageAsync(string name, string configPath, string embeddingModel = "");
public Task<(EmbeddedStorageInfo info, TryllError error)>
    RequestCreateEmbeddedStringStorageFromStringsAsync(string name, List<string> strings, string embeddingModel);
public Task<TryllError> RequestDestroyEmbeddedStringStorageAsync(string name);

// Events (main thread)
public event Action<bool>                    ConnectionChanged;
public event Action<TryllError>              Error;
public event Action<TryllError>              ConfigureSessionComplete;
public event Action<string, float>           DownloadProgress;    // (modelName, percent 0–1)
public event Action<string, bool>            DownloadComplete;    // (modelName, success)
public event Action<string, bool>            LoadModelComplete;   // (modelName, success)
public event Action<string, bool>            UnloadModelComplete;
public event Action<ulong>                   AgentDestroyed;
public event Action<ulong, string, string>   ToolCallNotification; // (agentId, toolName, argsJson)
public event Action<string, bool>            StringStorageChanged; // (name, isCreate)
public event Action<string, int, bool>       EmbeddedStringStorageChanged; // (name, recordCount, isCreate)

EmbeddedStorageInfo¶

public struct EmbeddedStorageInfo
{
    public string Name;
    public uint   RecordCount;
    public uint   EmbeddingDim;
}

TryllAgentComponent¶

MonoBehaviour that manages one TryllAgent lifetime on a GameObject.

// Inspector fields
public TryllWorkflowAsset    WorkflowAsset;
public TryllGraphDescription InlineGraphDescription;
public bool                  EnableDiagnostics;
public bool                  AutoCreateOnConnect;  // default true

// Runtime state
public TryllAgent Agent   { get; }
public bool       HasAgent { get; }

// Actions
public async void CreateAgent();
public void       DestroyAgent();
public void       SendMessage(string text);

// UnityEvents (wire up in Inspector or AddListener)
public AnswerTextEvent   OnAnswerText;    // (text, isDelta, isFinal)
public TurnCompleteEvent OnTurnComplete;  // (status, debugInfo, tokensGenerated)
public ErrorEvent        OnError;
public UnityEvent        OnAgentCreated;
public UnityEvent        OnAgentDestroyed;

Ownership: The component owns its agent. It calls Agent.Dispose() in OnDisable and OnDestroy. Do not retain the agent reference beyond the component's lifetime.

TryllAgent¶

IDisposable handle for a server-side agent.

public ulong AgentId { get; }
public bool  IsValid { get; }

// Actions
public void SendMessage(string text);
public void ChangeParam(string nodeName, string paramName, string paramValue,
                        Action<TryllError> onComplete = null);

// Lifetime
public void Dispose();

Warning: If you obtain a TryllAgent directly from TryllClient.RequestCreateAgentAsync (not via TryllAgentComponent), you own it and must call Dispose().

TryllError¶

Value-type error struct. Always check IsOk before using an API result.

[Serializable]
public struct TryllError
{
    public int    Code;        // 0 = OK. See TryllErrorCode enum for named values.
    public string Message;
    public bool   IsOk => Code == 0;
    public static TryllError Ok();
}

TryllErrorCode¶

Named error code constants. Values match the server ErrorCodes.h. See Error Codes for the full table.

public enum TryllErrorCode
{
    Ok = 0,
    // Connection: 1001–1003
    // Session: 2001–2002
    // Agent: 3001–3007
    // Inference: 4001–4003
    // Protocol: 5001–5004
    // Download: 6001–6004
    // StringStorage: 7001–7003
}

[Serializable]
public struct TryllGraphDescription
{
    public List<TryllNodeDescription> Nodes;
    public List<TryllExitRoute>       Routes;
    public string                     StartNode;
    public string                     DefaultModelName;
}

[Serializable]
public struct TryllNodeDescription
{
    public string              Name;
    public TryllNodeType       Type;
    public List<TryllNodeParam>      Params;
    public List<TryllToolDefinition> Tools;
}

[Serializable]
public struct TryllNodeParam { public string Key; public string Value; }

[Serializable]
public struct TryllExitRoute
{
    public string SourceNode;
    public string ExitName;
    public string TargetNode;  // use "END" to terminate
}

TryllGraphBuilder¶

Fluent builder for TryllGraphDescription.

var graph = new TryllGraphBuilder()
    .AddNode("gen", TryllNodeType.Generate, new() {
        new TryllNodeParam { Key = "model_name", Value = "mymodel" }
    })
    .Wire("gen", "done", "END")
    .SetStartNode("gen")
    .SetDefaultModelName("mymodel")
    .Build();

TryllWorkflowAsset¶

ScriptableObject that stores a TryllGraphDescription. Create via Assets → Create → Tryll → Workflow Asset.

public sealed class TryllWorkflowAsset : ScriptableObject
{
    public TryllGraphDescription Graph;
}

TryllRuntimeSettings¶

ScriptableObject loaded at runtime from Resources/TryllRuntimeSettings.asset. Edit via Project Settings → Tryll Client.

public static TryllRuntimeSettings Load();

public bool   AutoLaunchServer;      // default true
public string EditorServerExePath;   // Editor only; empty = launch manually
public string BuildServerExePath;    // default "tryll_server.exe"
public string ServerHost;            // default "127.0.0.1"
public int    ServerPort;            // default 9100

Enumerations¶

public enum TryllInferenceEngine : byte { Mock, LlamaCpp, OnnxGenAI, WindowsML, OpenVino, TensorRtLlm }
public enum TryllNodeType        : byte { Generate, HumanMessageGuardrail, CannedResponse, ToolCall, Retrieve }
public enum TryllTurnStatus      : byte { Success, Error, Cancelled }
public enum TryllModelStatus     : byte { Absent, Local, Downloading, Loaded, Downloaded }
public enum TryllKnowledgePlacement : byte { InPlaceOfUser, BeforeUserAsUser, BeforeUserAsSystem, AfterUserAsUser, AfterUserAsSystem }
public enum TryllKnowledgeAllEmptyBehavior : byte { UseAlternateTemplate, Skip }

TryllModelInfo¶

[Serializable]
public struct TryllModelInfo
{
    public string           Name;
    public TryllModelStatus Status;
    public string           HuggingFaceRepo;
    public long             SizeBytes;
}

Threading and error handling summary¶

All events and Task<T> completions fire on the Unity main thread.
Always check error.IsOk before using any Task<T> result.
Call TryllAgentComponent.SendMessage / CreateAgent from the main thread only.
Use await only from async void methods rooted on the main thread (e.g., async void Start()).