Skip to main content

Inputs (Start Point)

What this is​

Inputs define the data your tool expects before the workflow runs. You add and manage them on the Start point node of every tool.

Where to configure​

  • Open your tool in Studio.
  • Click the Start point node → side drawer opens.
  • Use the two tabs:
    • Inputs — add end-user inputs (Text, Long text, Number, File URL, Options, JSON).
    • Custom Attributes — attach dynamic variables and secrets (project/agent scoped).

Tip: The screenshots show exactly this drawer: Start Point → Inputs for adding fields, and Start Point → Custom Attributes for system/env variables.

Add an input​

  • In Start point → Inputs, click an input type: Text, Long Text, Number, File URL, Options, or JSON.
  • Fill:
    • Label name (shown to user)
    • Description (helper text)
    • Variable name (identifier used in steps, e.g., customer_id)
    • Required (toggle)
    • Default value (toggle + value)
  • Click Add.

After adding, each field shows a Test value box (only used when you Run in Studio).

Actions on a field:

  • ✏️ Edit the config
  • 🗑️ Delete the field

Input types (at a glance)​

  • Text / Long Text – short vs multi-paragraph strings.
  • Number – integers/decimals.
  • File URL – a URL pointing to a file your steps will fetch.
  • Options – provide a fixed set (e.g., ["basic","pro","enterprise"]).
  • JSON – paste structured JSON (great for complex payloads).

Defaults vs Test values​

  • Default value
    Saved in the tool. Used at runtime if the caller doesn’t supply a value.
  • Test value
    Not saved. Used only for Studio runs (tool-level or step-level tests).

If an input is Required and no value or default is present, validation fails before the flow runs.

Custom Attributes (dynamic variables & secrets)​

Open Start point → Custom Attributes.

System variables (sys.*) — read-only​

Provided by SimplAI (appear automatically):

  • sys.current_date_time_gmt
  • sys.user_id
  • sys.trace_id
  • sys.current_user_time
  • sys.user_timezone …and any other system entries available in your project.

Use them anywhere your steps accept templating (e.g., in prompts or headers).

Environment variables (env.*) — project-scoped, secure​

Use + Add New to create/update environment variables that:

  • Store secrets (toggle Secret to mask in UI/logs).
  • Allow overrides (toggle Enable override) so callers can set a value per run.
  • Are shared across agents, tools, and KBs in the same project.
  • Are available in agents & tools with the env. prefix (e.g., {{env.api_key}}).

You’ll see the same variables under Project Settings → Manage projects → Custom Attributes.
Editing them here or there is equivalent.

Value resolution at runtime​

When your tool runs, each field’s value is resolved in this order:

  1. Explicit input provided by the caller (API/SDK/embed)
  2. Inherited via Agent call (if the tool is invoked by an Agent and a matching env. variable was sent to the Agent for this run)
  3. Tool input Default value (if set)
  4. Otherwise → validation error if the field is Required

Studio Test runs ignore (3) only when a Test value is present in the drawer—test values win for Studio previews but are never persisted.

Using inputs inside steps​

Reference inputs and attributes with curly-brace templating in any step:

  • {{customer_id}} – a Start point input
  • {{env.crm_api_key}} – an environment variable
  • {{sys.current_user_time}} – a system variable

Examples:

  • API step header: Authorization: Bearer {{env.crm_api_key}}
  • LLM prompt:
    Summarize tickets for customer {{customer_id}} since {{sys.current_date_time_gmt}}

Agent → Tool parameter inheritance (no LLM copying)​

If a tool is called from an Agent, you can keep sensitive or operational parameters out of the Agent’s prompts:

  • Send run-specific values to the Agent as environment overrides (e.g., env.account_id, env.region, env.api_key).
  • When the Agent invokes the tool, those env values are automatically available inside the tool (and in any nested steps/tools) without the LLM needing to echo them as inputs.

This achieves:

  • Fewer prompt tokens (no leakage into LLM context)
  • Centralized, secure parameter passing
  • Consistent values across steps/tools in the same run

Good practices​

  • Name variables clearly: customer_id, date_from, plan_tier.
  • Prefer Options/JSON when structure matters; it reduces prompt ambiguity.
  • Use Defaults for sensible fallbacks (e.g., timezone = "UTC").
  • Keep secrets in env.*, never hard-code keys in prompts.
  • Enable override for anything you’ll vary per run from API/SDK.
  • Leverage system time (sys.current_date_time_gmt) instead of asking users to type dates.

Quick examples​

Research tool​

  • Inputs: topic (Text, Required), depth (Options: basic|detailed, Default: basic)
  • Custom Attributes: env.search_key (Secret, override enabled)
  • Usage: API step uses {{env.search_key}}; LLM prompt uses {{topic}} and {{depth}}.

Document QA​

  • Inputs: file_url (File URL, Required), question (Long Text, Required)
  • Defaults: none; Test values used during Studio validation.
  • System vars: include {{sys.user_timezone}} to adjust timestamp rendering.

Troubleshooting​

  • Value never arrives in a step: check the exact variable name and that you used {{...}} templating in the step field.
  • Unexpected old value: clear the Test value in the Start point drawer and re-run.
  • Agent call didn’t pass a parameter down: ensure it was sent as an env override and that the tool references {{env.var_name}} (not a plain input).

That’s it—your tool’s inputs are now cleanly defined, safely parameterized, and ready for reliable execution.