Tools

Tools are the actions the agent can take. There are twenty of them, and they are listed here in the order a normal session uses them.

A tool is never called by hand. The user describes what they want; the agent picks the tools. This page is here so that the names the agent reports mean something. The Workflow page explains the same process from the user's point of view.

Some tools only look at things and change nothing. Those are marked read-only, and the agent will usually run them without stopping to ask.

Getting started

Tool	What it does
init (read-only)	Always first, every session. Looks at the project folder, then asks about whatever is still undecided. If the builder has run here before, it reads back what was already decided instead. It also states the ground rules up front: the app belongs to the user, the payment code is written by tools, and secrets stay on the server.
save_app_spec	Writes the answers to a small file in the project (.nuvei/spec.json) - platform, payment methods, currency, how the backend is handled. Everything generated later is built from this one description, so the parts cannot drift apart.
install_skills	Copies the rules and skills into the project. Running it again for the same platform does nothing.

The design file never holds account details

save_app_spec rejects anything that names a secret key, a merchant id, or a server address that looks like a credential. The file is safe to commit.

What the design file looks like

Three sections: the app, the payments it takes, and how the backend is handled.

{
  "app": {
    "name": "...",
    "domain": "...",
    "platform": "android | ios",
    "theme": "...",
    "screens": ["..."],
    "payment_entry_point": "..."
  },

  "payments": {
    "products": ["..."],
    "environment": "...",
    "currency": "..."
  },

  "backend": {
    "mode": "scaffold | existing | deferred",
    "base_url": "https://api.example.com",
    "endpoints": { "open_order": "..." }
  }
}

The backend section is optional - leaving it out means the builder writes the example backend. base_url is only needed for a backend the merchant already runs, and it is that service's address, not a credential.

Account details

Tool	What it does
credentials_status (read-only)	Says which Nuvei account details are already in the computer's keychain. Yes-or-no answers only - it never reports the values.
open_setup_terminal	Opens a separate terminal window where the account details are typed in privately. The agent never sees that window's contents. It steals focus, so the agent should ask before opening it.

note

Both of these matter only when the builder is writing the example backend. When the app is wired to a backend the merchant already runs, or the endpoint is left for later, the builder has nothing to inject credentials into - an empty keychain is expected and blocks nothing.

Development tools

Tool	What it does
check_environment (read-only)	Checks what is needed to compile the app - the JDK, Android SDK, emulator, or Xcode on a Mac - and lists what is missing.
setup_environment	Installs what was missing, and creates an emulator. It cannot install Xcode itself; Apple only distributes that through the App Store.

iOS apps need a Mac

Everything else works on any computer - all the code can be written anywhere. Only the build and run step is tied to the machine. That is why the platform question comes early: if this computer cannot build the platform chosen, it is raised there and then, not several steps later when the build fails. If the flow carries on anyway, every result carries a reminder, and the build step ends the job cleanly rather than pretending it can retry.

The backend

Opening a payment order needs the merchant secret key, so it happens on a server, never in the app. There are three ways to handle that, and one is chosen during the interview:

• The builder writes one - an example backend that runs locally.
• One already exists - the builder wires the app to it.
• Later - the endpoint is written by the merchant afterwards; everything else still gets built.

Tool	What it does
inspect_backend_url (read-only)	Asks an existing server whether it already offers the endpoint the app needs.
scaffold_backend	Writes the example backend - a small Python service that holds the secret key and opens the payment order.
launch_backend	Starts that example backend, with the account details passed straight from the keychain into the running service. Never through the agent, never into a file.
stop_backend	Stops it again.

Checking an existing backend

inspect_backend_url reads the service's own API description, over a plain read request. It never touches a payment route and sends no data. It can also read a description file straight from the project, so the backend does not even have to be running.

There are four answers, and they are worth telling apart:

• endpoints_found - the service already offers the endpoint.
• no_endpoints - the service describes itself, and this endpoint is not in it.
• no_schema - it answered, but publishes no description, so nothing was actually checked. Point it at a description file, or give the agent the path directly.
• unreachable - nothing responded at all. Usually this only means the service is not running, so it is not the same as no_endpoints.

Starting and stopping

launch_backend only ever starts a backend the builder itself wrote. For a backend the merchant already runs, it refuses on purpose - the builder does not start, stop, or feed credentials into a service it does not own.

If the port is already taken, it starts nothing, reports who is holding the port, and offers a free one. If it starts something that then fails to answer, it shuts that process down rather than leaving it running. stop_backend will only stop a process it recognises as one of ours; anything else is left alone, and the agent should ask permission first either way.

Looking at the project, and wiring the payment

Tool	What it does
scan_workspace (read-only)	The look-first inventory the whole flow branches on: which platform the app is, whether payment code is already there and for which methods, whether a backend already lives in the folder, and what it recommends doing next.
scaffold_build_foundation	For a brand-new app only: lays down the bare project that compiles, and nothing else. No app, no payments - the app itself is the agent's to build on top.
integrate_nuvei	Writes the payment code into the app. Adds the SDK dependency, the payment layer, and the permissions the SDK needs. It only adds - existing screens and files are never overwritten. Anything it deliberately leaves out comes back as a short checklist.
modify_nuvei	Changes an app that already takes payments. Adds another payment method without touching the rest, or - only when asked - regenerates one method's code. This will overwrite any hand edits that were made but the agent tells the user about this before proceeding.
integration_check (read-only)	Goes through that checklist: is the payment code there, is the dependency declared, is the SDK started when the app starts. Best run before spending time on a build.

Building and running

Tool	What it does
build_app	Compiles the app. Android uses a pinned, known-good build setup; iOS generates the Xcode project and builds for a simulator. It retries once automatically on a known Windows file-locking hiccup.
launch_app	Installs and starts the app - booting an emulator or simulator first if nothing is running - and checks the app can actually reach its backend. A dead backend is caught here.

What "finished" means at this point depends on the backend choice:

Backend choice	What finished looks like
The builder wrote one	The app is running against a live local backend.
One already existed	The app is running. The builder does not probe a service it does not own, so it gives a reminder to check that backend is up.
Later	The app is running, but no payment can go through until the endpoint exists.

Testing the payment

Android only, for now

Both tools below are implemented for Android only. iOS support is planned; until it lands they do nothing on iOS but say so, and the payment is handed back to the user to run by hand.

The last step on Android: the builder drives a real sandbox payment through the running app, so the flow ends with proof the whole chain works rather than proof the app compiled. See Run an End-to-End Test Payment.

Tool	What it does
plan_payment_route (read-only)	Reads the app's own source to find where it starts a payment, and proposes the exact steps that reach that screen - one route per payment method, each step naming its target exactly. Steps it could not resolve are flagged as low confidence rather than guessed at. Its one change to the project is turning on Compose test tags when they are missing, because nothing outside the app can see its buttons without them.
run_payment_test	Replays that route, taps the control that starts a payment, waits for the Nuvei checkout, types a sandbox test card, and reads the gateway's answer out of the app's own log. One run per payment method, with screenshots kept.

What the payment test will and will not do

The card is typed by the tool, from a fixed list of Nuvei's published sandbox cards - the agent is never given a card number. A declined payment is a pass: reaching any gateway answer proves the backend, the token, the SDK and the wire all work. Only a checkout that never appeared, or a crash, is a failure.

A failing run earns exactly one fix-and-retry attempt, then the tool refuses to run again until the user says to continue. The agent is also not allowed to tap through the payment by hand instead - that would look like a pass and prove nothing.

The emulator is the default target; a real device has to be allowed explicitly, because a payment there can move real money. Google Pay is reported as skipped on an emulator, and on a real device it runs only after the user answers the device question themselves.