Skip to main content

Input Parameter Mapping

Part of a skill's configuration often needs to change with each execution. Input parameter mapping carries a value from the agent execution request into your agent's input parameters and makes it available as a Liquid variable inside a skill. A single skill definition can then serve many requests, with the caller supplying the variable parts at execution time.

How the mapping flow works​

Mapping a value from a request into a skill is a four-step chain.

  1. Define the input parameter on the agent. In the Agent Designer, add an input parameter. Its name is the key referenced everywhere else. See Input Parameters.

  2. Reference it as a Liquid variable in the skill. Use the token {{parameterName}} in the skill's configuration wherever the value should be injected.

  3. Pass the value in the execution request. Execute the agent with a key/value pair whose Key matches the parameter name and whose Value is the runtime value.

  4. The value is resolved before the skill runs. The platform substitutes every matching token, then the skill executes with the resolved configuration.

Resolving values into Liquid variables inside a skill​

Any skill that supports Liquid tokens can reference a mapped parameter with the {{name}} syntax. The token is replaced with the value supplied for that execution. Common places it applies:

  • HTTP Request skill — in a route or query parameter, a header, or a request body field. See the HTTP Request skill.
  • Prompt skill — in the prompt text.
  • Agent system definition — the same token works here, so a mapped value can shape both the agent and its skills in one execution.
Liquid resolution vs. AI-filled values

Input parameter mapping resolves values deterministically from the request, before the model runs, unlike values the AI infers from the conversation. Use mapping when the caller already knows the value and it must be exact.

Request examples​

Map a value into an HTTP Request skill​

An HTTP Request skill whose URL is https://api.example.com/customers/{{customerId}}/orders resolves customerId from the request before the call:

cURL
curl https://api.serenitystar.ai/api/v2/agent/YOUR_AGENT_CODE/execute \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '[
    { "Key": "message", "Value": "List this customer'\''s recent orders." },
    { "Key": "customerId", "Value": "12345" }
  ]'

{{customerId}} resolves to 12345, so the skill requests .../customers/12345/orders.

Map several values at once​

Every input parameter you send is available to the agent and its skills for that execution:

cURL
curl https://api.serenitystar.ai/api/v2/agent/YOUR_AGENT_CODE/execute \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '[
    { "Key": "message", "Value": "Draft a reply to this customer." },
    { "Key": "customerId", "Value": "12345" },
    { "Key": "tone", "Value": "formal" },
    { "Key": "language", "Value": "British English" }
  ]'

Each of these can be referenced independently in the system definition and in any skill that supports Liquid tokens.

Rules and notes​

  • The request Key must match the input parameter name exactly for the value to map (matching is case-sensitive).
  • A parameter marked Required must be present in the request, or the execution fails. Optional parameters fall back to their default value when omitted. See the Input Parameters page for the accepted value shapes per type.
  • Reserved keys such as skills, volatileKnowledgeIds, and audioInput are not input parameters and are not mapped as Liquid variables.

For the full request and response schema, see the Execute agent endpoint in the API reference.