Skip to content

Map and transform API responses

Use response processing to choose which parts of an API response the Agent receives. For example, keep only the customer name and delivery status from a detailed order response.

Choose a mode

Mode Use it for
Original response An already small, useful response
Mapped response Selecting and naming JSON fields
JEXL script Calculations, filtering or a different output structure

Pre-processing offers the corresponding modes Whole response, JSON fields and Script. The output becomes caller context there, rather than a tool result.

Map fields visually

Load a sample response or run a controlled API test, open the mapping editor and choose the fields to retain. Give each output field a meaningful name.

For this synthetic response:

{"customer":{"name":"Example Caller"},"orders":[{"status":"ready"}]}
Output name Path
customer_name $.customer.name
first_order_status $.orders[0].status

Select individual fields, list entries such as $.orders[0].status, or multiple entries such as $.orders[*].status. Not all JSONPath expressions are supported. Check the selection in the preview with missing fields and empty lists too.

Write a JEXL script

Scripts use JEXL, not JavaScript. response contains parsed JSON. For API tools, request.path, request.query and request.body contain the request inputs.

return {
  'customer_name': response.customer.name,
  'first_order_status': response.orders[0].status
};

This example requires a customer and at least one order. For optional structures, add checks such as data:hasKey(...) and size(...) before accessing them. Use the editor's function reference for helpers including data:trim, data:take, data:addMinutes and date:now.

The result must be representable as JSON. Use the functions listed in the editor’s reference. Network calls and external JavaScript libraries are not available in these scripts.

Validate the result

  1. Validate syntax.
  2. Preview against representative sample JSON. This does not repeat the original API request.
  3. Test missing and malformed data.
  4. Run a controlled real request and compare raw and processed results.
  5. Verify the Agent's response in a call.

RESPONSE_MAPPING_FAILED or RESPONSE_SCRIPT_FAILED means response processing failed. Check the field paths or script against the response the service actually returned.