Skip to main content

Custom Attributes (Environment Variables)

Custom Attributes let you inject private, project-scoped values into agents, tools, and KBs at runtime. They’re ideal for things like default locales, feature flags, or per-project credentials—without hard-coding them in prompts.

Scope & safety​

  • Available across all agents, tools, and KBs in the same project.
  • Excluded from exports; safe to keep out of DSL/config files.
  • Read-only in runs; values can be overridden per API call for a single run.
  • Overrides persist through the whole run (agent → tool → nested tool).

When to use​

  • You need a project-level constant (e.g., default region, support queue).
  • You want a value that UI runs can use by default, but which backends can override per request.
  • You need to surface dynamic system values (current time, user/timezone) into prompts.

Where you configure​

A. From an Agent​

  • Open the agent → Edit.
  • Click Custom Attributes → Config (top of the page).
  • In Environment, click Create and fill details (see “Create a variable”).
  • You’ll also see a System list of built-ins (read-only).

B. From Project Settings​

  • Go to Settings → Manage projects → Your project → Custom Attributes.
  • Create variables once and reuse them across agents/tools/KBs in this project.

New variables created in either place are available across the entire project.

Variable types​

System variables (read-only, auto-populated, prefixed sys.)​

Common examples you’ll see in the System list:

  • sys.current_date_time_gmt — current date/time in GMT
  • sys.user_id — SimplAI user ID
  • sys.trace_id — execution trace/message ID
  • sys.current_user_time — current date/time in the end-user’s timezone
  • sys.user_timezone — end-user timezone (e.g., America/New_York)
  • sys.language_code — end-user browser/system language (e.g., en-US)

Availability can vary by integration; check the System table in your project.

Environment variables (project-scoped, prefixed env.)​

  • Your custom values (short text, etc.).
  • Prefix is enforced at creation (name will start with env.).
  • Provide a default value for UI runs / when no API override is sent.

Create a variable (Environment)​

  • Variable Name — starts with env. (e.g., env.default_locale).
  • Data type — e.g., Short text.
  • Variable Description — optional helper text.
  • Value — default used by UI and by API calls that don’t override.
  • Enable override — keep Enabled to allow per-run overrides via API.
  • (Optional) Secret — mark sensitive values as secret.

Click Add to save.

Use in prompts & tools​

Templating syntax​

Embed values anywhere the platform supports templating:

  • Current date/time (GMT): {{sys.current_date_time_gmt}}

  • Test custom attribute value: {{env.test}}

  • {{sys.*}} → system (dynamic) variables

  • {{env.*}} → your environment variables

The same templating works in Agent Base instructions, Tool inputs, and Tool nodes in Conversation mode.

Best practices​

  • Name clearly: env.default_locale, env.sales_queue_id, env.region.
  • Keep secrets out of prompts where possible; use tools that accept secrets directly.
  • Prefer project-wide config in Settings for consistency; edit at the agent level when experimenting.
  • Use sys.language_code / sys.user_timezone to auto-personalize replies.
  • Treat sys.* as read-only hints for prompt logic (don’t try to override them).

Troubleshooting​

  • Value didn’t change during a run → Overrides are evaluated once at run start and held constant; start a new run to change them.
  • Template didn’t render → Check the prefix (env. / sys.), exact variable name, and that the variable exists in the project.
  • Tool didn’t see the override → Confirm override was sent; overrides propagate automatically to tools only within the same run.
  • Variable missing in export → Expected (custom attributes are not included in exports).

With Custom Attributes, you separate configuration from logic: define once, reuse everywhere, and safely tune behavior per project or per run—without editing prompts.