Skip to content
RasaGet a free license
Menu
Guides for AI teams

Guide

Handling Jack Henry Symitar API Changes in a Voice Agent.

Check whether changed Jack Henry Symitar API definitions still fit your voice agent, including replies that old samples never covered.

by Rod Rivera

About 13 minutes to readAI product engineer

Key takeaways (3)
  • Compare file bytes when a vendor download has a newer date.
  • Test the requests you send and the replies you might receive, including replies your old examples never covered.
  • Inspect the tool trace to see whether an account refusal came from the model alone or followed a banking-tool call.

You maintain a voice agent against Jack Henry Symitar. Yesterday’s response still validates against new API definitions. Is that enough to accept the new files?

One contract test in this example makes the transaction list, transactions, optional. The old sample still fits because it contains the field. A future reply could omit it. The example stops the candidate files anyway: it checks the declared replies as well as the old samples.

Contract in the testDoes the old sample fit?What can the next reply do?Example’s decision
The transactions field is required.Yes; it contains the field.It must contain the field.Use the tested definition.
The transactions field becomes optional.Yes; it still contains the field.It may omit the field.Stop for review.

That conservative rule costs maintenance time. You review an expanded reply even when you think the agent could handle it. The alternative is accepting possibilities your old sample never covered.

You will follow the example’s real vendor-file history, run its compatibility checks, and inspect an account refusal. The download date, the file bytes, the declared replies, and the model’s answer are separate evidence. The test behind the table is shown below.

What you will learn

  • Identify downloaded files by their bytes, rather than their publication date alone.
  • Connect a vendor declaration change to the requests and replies your own integration uses.
  • Explain why a reply that becomes less restrictive can still require a code review.
  • Reopen a saved fictional exercise and inspect what actually handled an account question.

An old reply still contains the transaction list after the API makes it optional. The example stops for review because the next reply may omit it.

What you need

Use the Symitar example and its setup instructions. Its Codespaces badge opens the moving main branch. Start a fresh Codespace, wait for READY, and use its terminal in examples/jack-henry-symitar.

Before uploading vendor files or starting a conversation, select the implementation that produced the receipts:

git checkout --detach b26628b8038b813ae39cc97b5347bafb005013a1
uv sync --locked
git rev-parse HEAD

These are source-selection instructions, not additional recorded test output. The last command must print the full commit shown above. If checkout reports local changes, preserve them and start a fresh Codespace rather than discarding them. If dependency synchronization fails, stop and resolve that error before comparing results. Keep the linked setup README open separately: its later correction changes documentation only.

The keys page explains the required personal Codespaces secrets. The assistant uses external model services; use fictional information. The input check and contract tests below do not connect to a bank.

Download the four original YAML files from the official links in the example’s README. Upload each to its listed folder under vendor-inputs/. YAML is the text format used for these API definitions. Save the file itself, rather than the webpage that displays it. Keep your original downloads for the exercise at the end.

If the folders are missing, this is the command used in the recorded setup:

mkdir -p vendor-inputs/accounts vendor-inputs/transactions vendor-inputs/loans vendor-inputs/transfers

The files stay in your example environment. The repository does not supply copies of Jack Henry’s definitions, and this example has no make download target.

The run used companion revision b26628b8038b813ae39cc97b5347bafb005013a1, Rasa Pro 3.21.0.dev5, and Python 3.12.11. Those versions identify the evidence below. If you use a later revision, compare its README and recorded results before expecting the same behavior.

1. Separate the website date from the file version

Open the example’s version table beside its changelog.

The table keeps old file fingerprints. A SHA-256 hash is a fingerprint calculated from a file’s exact bytes. It identifies the file you tested. A web address alone cannot do that when its owner replaces the download at the same address.

The changelog records this sequence:

Recorded versionDeclaration changeEffect on this example
Accounts published on November 12, 2026, at 7:31 PM UTCAn optional member filter was added to the two account lookups.The example did not send that filter.
Files published on November 12, 2026, at 10:38 PM UTCThe filter became a list; three definitions also documented a not-found reply. The transfer file did not change.The changelog records no effect on the requests and successful replies used here.
Download on November 13, 2026The website returned a later Last-Modified header.Every downloaded file still matched the stored fingerprint.

For the second row, the request field changed from memberNumber to memberNumbers. That is a declaration change, not evidence of an outage. You must look at what the integration sends before deciding whether the rename affects it.

The third row is a separate observation. The download receipt contains this response header:

last-modified: Fri, 13 Nov 2026 14:25:05 GMT

Yet all four hashes matched the files recorded as published the previous evening. The version table explains that the website updates the date for all four files together. Treat the header as information about the website, then check the bytes.

2. Identify the files you actually uploaded

From the example terminal, run the recorded hash command:

sha256sum vendor-inputs/*/*.yaml

Our output was:

d6370f663f53973dfc52d931333bdc350dc39f6c2680998a9054030668b4820f  vendor-inputs/accounts/accounts.yaml
2631ee0b97790009624ca3f9c8d233855d0ecf06556a8f0134770a831801c914  vendor-inputs/loans/loans.yaml
9662089e4943dea29e8d109419388bb971301890f0ca07a4a2eff55cee19fe8d  vendor-inputs/transactions/transactions.yaml
bd5ec66744b21cb3632d37e2cbdb53bbf7f3bd79cb7047cafafa9caca186de95  vendor-inputs/transfers/transfers.yaml

Compare all four lines with the version table. A different hash tells you that the bytes differ. It does not tell you whether a change matters to the integration.

Do not edit the expected hashes to silence that difference. Keep the known version as your comparison point and let the next check examine the new files.

3. Check the traffic your integration uses

Run:

Any system
make check-inputs

The recorded output was:

uv run --locked python run_demo.py --check-inputs
All four manual vendor inputs are readable and accept everything this example sends and reads. No bank connection.

The example stores fictional request-and-reply pairs in recorded_exchanges.py. They cover its six selected vendor operations, including the replies and refusals it handles. The checker validates those messages against the uploaded definitions.

There is another check beyond replaying the samples. For each used operation, it compares the declared replies with the replies in the tested version. It leaves out documentation annotations, but keeps the fields, types, required values, and declared response cases.

Why is that necessary? Suppose a reply previously required an amount. A new definition makes that amount optional. Your old sample still contains it, so the sample passes. A future reply could omit it. Your sample did not test that possibility.

The example therefore stops for a changed reply definition, even if its recorded replies still fit. That rule costs maintenance time: someone must inspect and accept even an apparently harmless reply expansion.

A recorded sample and the next allowed reply are different checks
FigureA recorded sample and the next allowed reply are different checks

The old sample can pass while the declared replies expand. The second check catches that expansion and sends it for review.

Candidate changeWhat the check needs to establishExpected decision in the recorded tests
Descriptive prose changesUsed request and reply rules are unchanged.Accept.
A used request gains a required fieldExisting requests still satisfy the new requirement.Stop when the recorded request lacks it.
A reply field becomes optional or allowed to be nullThe integration has evidence for the newly possible reply.Stop for review, even if old samples validate.
A field keeps its type but changes its business meaningThe meaning still fits the application.Review its meaning with the API owner.

The last row needs a person who understands the API. A field can remain a string while its meaning changes.

4. Read the tests behind that decision

Run the recorded test target:

make contract-test

The summary from this run was:

----------------------------------------------------------------------
Ran 30 tests in 22.515s

OK

There were no failures or skips. The first-screen counterexample is the optional mutation inside test_a_relaxed_or_otherwise_changed_reply_stops_even_though_old_replies_still_fit. It removes one item from the response’s required-field list. Removing that requirement leaves an old reply containing the field valid. The test expects the changed reply definition to stop the example.

Read these cases in tests/test_vendor_contract.py:

  • test_documentation_changes_and_a_new_optional_request_field_still_load checks compatible changes.
  • test_a_change_the_recorded_traffic_no_longer_fits_stops_and_names_it includes making memberNumbers required on searchLoans.
  • test_a_relaxed_or_otherwise_changed_reply_stops_even_though_old_replies_still_fit covers newly permitted replies with missing values, nulls, or a wider set of values.

These are deterministic contract tests. They support the checker’s decisions over the supplied definitions and fictional messages. Pair them with a tool trace when you inspect a conversation.

5. Start from a known fictional exercise

On the first start, run:

make run

Wait for Rasa server is up and running, then stop that copy with Ctrl+C before resetting anything. The first run in the receipts chose and stored this seed:

Demo data seed: 489386; set DEMO_SEED=489386 to get the same data again.

A seed selects the exercise’s starting fictional data. It does not fix the model’s wording. The reset and later reopen in the receipts printed the same saved seed.

To reproduce this exercise after the first start, stop every running copy and use the recorded reset command:

DEMO_SEED=489386 make reset-fixture REASON="new fictional exercise"

Its output was:

uv run --locked python run_demo.py --reset-fixture --ack-unknown --reason "new fictional exercise"
Demo data seed: 489386; set DEMO_SEED=489386 to get the same data again.
New fictional epoch created. Original state and audit are retained; no old transfer was resolved or retried.

Then run make run again. The later recorded startup printed this combined mode line:

Mode: fictional local mock, four vendor input hashes verified. Routing identity is a simulator, not bank authentication.

Follow the printed Inspector link for your own typed questions. The recorded conversation in the next section used the REST text channel instead; it does not qualify the Inspector interface or microphone path.

6. Check what handled the unavailable-account request

Ask these questions in the same conversation:

What is available in checking?
What is available in checking-B?

Here is the complete transcript section retained for the two typed REST turns. The server used uv run --locked python run_demo.py --text-api, with the same saved seed:

[2026-11-13T15:39:32Z] USER (sender=step7-other-account): What is available in checking?
  HTTP 200; raw REST response body: [{"recipient_id":"step7-other-account","text":"The available balance in your checking account is $898.12."}]
  ASSISTANT: The available balance in your checking account is $898.12.
[2026-11-13T15:39:39Z] USER (sender=step7-other-account): What is available in checking-B?
  HTTP 200; raw REST response body: [{"recipient_id":"step7-other-account","text":"The account checking-B is not available to me."}]
  ASSISTANT: The account checking-B is not available to me.

The available balance was fictional and specific to this exercise. The second answer refused checking-B; it did not substitute the balance from checking.

There is an important limit to that observation. The server trace dispatched banking_balance for the first question. This is the exact dispatch event:

2026-11-13 15:39:36 INFO     rasa.mantle.orchestration.orchestrator  - {"tool_name": "banking_balance", "iteration": 1, "event": "mantle.tool.dispatched", "conversation_id": "step7-other-account", "level": "info"}

For the second question, the complete retained turn interval is:

2026-11-13 15:39:39 INFO     rasa.mantle.orchestration.orchestrator  - {"active_flow": "banking", "stack_depth": 1, "event": "mantle.turn.started", "conversation_id": "step7-other-account", "level": "info"}
2026-11-13 15:39:39 INFO     rasa.mantle.hooks.runner  - {"point": "model_request", "lane": "modify", "outcome": "success", "duration_ms": 0.19, "hook_name": "banking_alias_context", "event": "mantle.hooks.execution", "conversation_id": "step7-other-account", "level": "info"}
2026-11-13 15:39:40 INFO     rasa.mantle.hooks.runner  - {"point": "model_response", "lane": "modify", "outcome": "success", "duration_ms": 0.13, "hook_name": "banking_host_reply", "event": "mantle.hooks.execution", "conversation_id": "step7-other-account", "level": "info"}
2026-11-13 15:39:40 INFO     rasa.mantle.orchestration.orchestrator  - {"iteration_count": 1, "source": "llm_text", "error": null, "event": "mantle.turn.completed", "conversation_id": "step7-other-account", "level": "info"}

The interval starts with mantle.turn.started and ends with mantle.turn.completed. Hook events appear, but no mantle.tool.dispatched event appears between them. A hook is code run around the model request or reply; it is not a dispatched banking tool. Here, banking_alias_context supplied the permitted-alias list to the model before its request. The model had that host-controlled context for this fictional caller. Its refusal was model-worded, while the guarded account tool was not dispatched.

To inspect your own questions, keep the terminal running the assistant open. It prints these events as well as the Inspector address. Find the conversation’s conversation_id and match the turn times to your questions. Read the interval from mantle.turn.started through mantle.turn.completed, looking for mantle.tool.dispatched and its tool_name. Do not count a successful hook event as a tool call.

The readable conversation trace includes every event for this conversation from the original server log. Its header records the selection and the original file’s SHA-256. The display copy removes one leading terminal escape marker and preserves every later selected byte.

The host is the application code that decides whether an account operation can proceed. When that guarded tool path receives an unavailable account, its fixed response is:

That account is not available to you. Nothing was read or sent.

The host code and its deterministic tests establish that separate behavior. The sampled turn has no tool dispatch to that path. Read native_host.py, lib/native_adapter.py, and the unavailable-account tests in tests/test_native_host.py and tests/test_native_transport.py together.

For your own check, inspect both the caller’s answer and the tool trace. A refusal sentence alone is not evidence that the guarded account tool ran. Keep a model-only observation separate from a host-enforcement result.

Exercise: change the description, keep the comparison

Stop the assistant. In your uploaded transfers.yaml, find the description near the top that describes the API itself. Add Changed by the reader for the exercise. before its existing text. Keep the YAML indentation and the rest of the file intact.

This edits descriptive prose, not a schema field that happens to be named description. Keep your unchanged original download so you can restore it afterward.

Run make check-inputs. For that edit, our recorded result was:

uv run --locked python run_demo.py --check-inputs
Your Jack Henry files differ from the ones this example was tested with (Jack Henry Symitar files as published 12 Nov 2026, 22:38 UTC); everything this example uses is unchanged.
All four manual vendor inputs are readable and accept everything this example sends and reads. No bank connection.

The file fingerprint changed, but the contract check accepted the description edit. The expected hash in the code was left alone.

Restore the unchanged file and run the check again. In the recorded exercise, a fresh download restored the original fingerprint and returned the baseline output. Keep your own original: a URL that serves the newest file is not an archive of an older one.

What if the vendor made the member filter required?

Find the require_new_field case inside test_a_change_the_recorded_traffic_no_longer_fits_stops_and_names_it. It adds memberNumbers to the required request fields for searchLoans.

The existing request does not supply that field. The test expects the example to stop and name the operation. The description exercise preserves what the request must contain; this change does not.

What to carry into your own integration

Keep the downloaded file identity, the used-contract check, and the conversation result as separate evidence. Preserve the old hashes when you review new files. Test newly possible replies as well as old examples. When you inspect an account refusal, check whether the host actually handled the request.

This example’s CHANGELOG.md, VENDOR-FILES.md, contract tests, and seeded receipt set are the source of that method. They support a local simulation and specific recorded observations. A real credit-union integration needs its own authentication, business-meaning review, and operational evidence.

Evidence and limits

The contract-test component receipt qualifies the downloaded-file checks and their tests. The conversation is a separate historical observation.

Not claimed: Trained agent, model, voice, vendor, or current global release acceptance.

The command receipts were captured on November 13, 2026, against companion commit b26628b8038b813ae39cc97b5347bafb005013a1. Setup recorded Python 3.12.11 and Rasa Pro 3.21.0.dev5. The account conversation used two model-backed Mantle turns through the REST text channel and fictional seed 489386. The checked-in configuration selects OpenAI gpt-4o-mini. The transcript omits per-call provider model identifiers.

The download receipt, input check, 30-test contract run, fresh start, reset, reopened start, two-turn conversation, and description exercise are retained separately. This guide uses those retained runs. The contract checks are local; running the assistant uses external model services. These receipts establish typed local observations. Voice testing needs its own audio recording and completion evidence.

The setup link uses the README-only correction at 2eabe560d678b4bfafdd34436a52fa06943b815a. That change restates the evidence limits; it changes no implementation file. The recorded runtime evidence remains tied to b26628b8038b813ae39cc97b5347bafb005013a1.