Skip to content

String Storage

A string storage is a session-owned, named container of plain text strings. It exists for two purposes:

  1. To back a canned-response node with a set of fixed replies.
  2. To back a human-message-guardrail node with a set of regex patterns to match against the user's message.

String storages are not embedded and not indexed. For vector retrieval, see embedded string storage.

Lifecycle

Step Frame Notes
Create CreateStringStorageRequest Sent before CreateAgentRequest. Server responds with CreateStringStorageResponse.
Use (referenced by node string_storage param) Scoped to the session.
Destroy DestroyStringStorageRequest Server responds with Ack. Agents that already hold the storage keep it alive — the call only removes the session's named reference.

The session drops every storage it owns on disconnect. See Lifetime and Ownership → StringStorage for the full ownership model, including what happens when you Destroy a storage that live agents still reference.

Creation

CreateStringStorageRequest has two mutually exclusive content paths:

Field Type Description
name string Unique name within the session. Required.
strings [string] Inline string list. Use for small, programmatically-generated content.
file_path string Server-side path to a UTF-8 text file. Use for content edited out-of-band.

Exactly one of strings / file_path must be set; an empty strings list is rejected with error 7003 InvalidStringStorageData.

File format

When file_path is used, the file is UTF-8 text, one entry per line:

# Lines starting with # are comments and are ignored.
# Blank lines are also ignored.

I can't help with that.
I can't assist with that request.

Relative paths in file_path are resolved against the server's current working directory, not the client's. For portable setups, use absolute paths or rely on the server defaults (see below).

Server defaults

If a canned-response or guardrail node is created with no string_storage param and no inline response_N / pattern_N params, the server falls back to a file the operator has configured in server-config.json. This is a server-admin fallback — client workflows should create a storage explicitly via CreateStringStorageRequest (inline or file_path) rather than rely on operator defaults:

  • default_canned_responses_path — default responses for canned-response nodes.
  • default_guardrail_patterns_path — default patterns for guardrail nodes (regex, matched case-insensitively).

Both files are loaded lazily (on first use) and fall back to a small hardcoded list if missing.

Resolution order

A canned-response or guardrail node resolves its string source in this order:

  1. Named storage — string_storage param set → look up in the session's StringStorageManager.
  2. Inline params — response_0 / pattern_0 (etc.) set → use as-is.
  3. Server default — load from the configured default file.

Minimum working example

client.create_string_storage(
    name="refusal_lines",
    strings=[
        "I can't help with that.",
        "That's outside what I can do.",
    ],
)
# ... then reference "refusal_lines" from a CannedResponse node
# via the `string_storage` param.

client.CreateStringStorage("refusal_lines", {
    "I can't help with that.",
    "That's outside what I can do.",
});
// ... then reference "refusal_lines" from a CannedResponse node
// via the `string_storage` param.

auto* subsystem = GetGameInstance()->GetSubsystem<UTryllSubsystem>();
subsystem->RequestCreateStringStorage(
    TEXT("refusal_lines"),
    { TEXT("I can't help with that."),
      TEXT("That's outside what I can do.") });
// Bind OnCreateStringStorageComplete to proceed once it lands.

See the full flow in the canned-response how-to.

Errors

Code Cause
7001 Name empty, malformed, or reserved.
7002 A storage with this name already exists in the session.
7003 Content rejected: unreadable file, empty array, bad format.

Client bindings

  • C++: Tryll::TryllClient::CreateStringStorage / CreateStringStorageFromFile — TryllClient.h
  • Python: tryll_client.TryllClient.create_string_storage (pass either strings=… or file_path=…) — client.py
  • Unreal: UTryllSubsystem::RequestCreateStringStorage — TryllSubsystem.h