Map Data and Context

Agent Studio does not expose one global bag of data. Every action, compound action, resolver, conversation process, and system trigger has a scoped runtime data bank.

Mappings create explicit bridges between those scopes.

Explore the Data Boundaries

The Data Bank by Surface

Understand the Mapping Layers

Input Mapping

Input mapping supplies an action activity’s typed input arguments from the parent conversation process:

feature_request_id: data.selected_feature_request.id
new_status: data.target_status.value

It answers: What does this action receive?

Output Mapping

Output mapping reshapes the current action payload, referenced as response:

feature_request:
  id: response.id
  name: response.name
  status: response.currentStatus
display_instructions_for_model: >-
  Confirm the feature request name and its new status.

Unmapped response fields do not remain in the exposed activity output.

It answers: What does the conversation and reasoning engine receive?

Compound Action Input Arguments

A compound action declares typed entry points. Each internal action block uses input_args to receive exact values from the compound data bank.

It answers: What crosses into this backend workflow and each internal step?

Compound Action Return

The final return.output_mapper creates the compound action’s public result:

- return:
    output_mapper:
      feature_request:
        id: data.updated_request.id
        name: data.updated_request.name
        status: data.updated_request.currentStatus

Intermediate action outputs stay internal unless you return them.

It answers: What crosses back to the caller?

Choose the Right Language

Replace Outputs Intentionally

An output mapper rewrites the exposed output. It is not an annotation layered over the original response.

If you map:

accounts:
  MAP():
    items: response.data
    converter:
      id: item.id
      name: item.name

Then downstream steps receive accounts, not the original payload plus accounts.

Use this behavior to:

• Remove metadata, debug fields, and unused nested objects.
• Rename keys to describe business meaning.
• Normalize inconsistent provider schemas.
• Limit arrays before they enter conversational context.
• Add display_instructions_for_model when presentation needs light steering.

Shape Context for the Reasoning Engine

The reasoning engine sees each output exposed by a conversation action activity. It does not need every API response or internal backend step.

Prefer:

{
  "request_id": "FR-1042",
  "request_name": "Bulk edit requests",
  "new_status": "Planned"
}

Avoid:

{
  "lookup_response": {},
  "validation_response": {},
  "patch_response": {},
  "audit_response": {},
  "raw_headers": {}
}

When several calls run without user interaction, use a compound action and return one concise object.

Use Display Instructions as Steering

display_instructions_for_model can guide how the assistant presents a result:

display_instructions_for_model: >-
  State the feature request name, current status, and product area.
  Do not mention internal record identifiers unless the user asks.

Treat this field as presentation guidance, not a deterministic business rule. Use DSL, policies, mappings, or code when a rule must always hold.

Build Along: Map the PurpleSuite Contracts

Create the explicit bridges for the feature-request build:

selected_feature_request:
  id: <data[n].id>
  display_name: <data[n].name>
  current_status: <data[n].currentStatus>
  product_area: <data[n].productArea>

1. Map the list action’s response array into resolver candidates with id, display_name, and current_status.
2. Map the selected object’s stable ID and the static resolver’s raw status into the compound action.
3. Return only the updated request’s name and status to the conversation.

Use this conversation-to-compound input mapping:

feature_request_id: data.selected_feature_request.id
new_status: data.target_status.value

Use this conversation activity output mapping:

updated_feature_request:
  name: response.feature_request.name
  status: response.feature_request.status
display_instructions_for_model: >-
  Confirm the feature request name and its new status.

Inspect the Data Bank at each boundary. Your checkpoint is that the raw list response and internal PATCH and verification responses do not enter conversational context.

Deep Dives

• Data Bank
• Conversation Process Data Bank
• Action Activities
• Common DSL and Mapper Patterns
• Data Mapper Reference
• DSL Reference
• Plugin Responses

Next, collect slots and resolve values.