AI tooling best practices

Tool selection, prompting best practices, and troubleshooting for Airwallex AgentOS and the developer connectors

This page covers how to get the most out of Airwallex's AI toolkits — AgentOS for acting on your production account, and the developer connectors for building and testing integrations. Pick the right tool for the task, follow the prompting best practices below, and refer to the troubleshooting guidance if you hit issues.

Choose the right tool

Start by matching your task to a toolkit, then pick the connector within it.

Building or testing an integration — use the developer connectors.
Operating on your production Airwallex account — use AgentOS.

Developer connectors

Documentation lookups only — use the Docs MCP. No authentication, no rate limits on agent operations.
Building or testing an integration — use the Developer MCP. It connects to the Airwallex sandbox so the agent can create test resources and simulate events.

AgentOS connectors

AgentOS connects agents to your production account through two connectors:

Production reads and writes from a terminal or scripted environment — use the Airwallex CLI. It has the broadest API coverage and is well-suited for power users, scripts, and CI.
Production reads and writes from a chat UI or non-terminal agent — use the Airwallex AgentOS MCP.

Not sure which one fits your setup? See Which AgentOS connector do I need? for a side-by-side comparison.

Use skills for common AgentOS workflows

If your task matches a domain workflow that AgentOS already ships, use the skill instead of prompting from scratch. Skills handle multi-step orchestration — document extraction, validation, resource lookup, and CLI invocation — with guardrails baked in.

Examples of skill-fit tasks:

Turning a signed contract into invoices and subscriptions (contract-to-billing).
Creating beneficiaries from supplier onboarding documents (beneficiary-creation).
Issuing a card with spend limits to a new hire (card-provisioning).
Building a multi-currency cashflow report (manage-cashflow).

Follow prompting best practices

Apply these practices when working with your AI assistant to improve the accuracy and relevance of responses. They apply to both the developer connectors and AgentOS.

Always mention "Airwallex" in your prompts

When asking your assistant about Airwallex products, APIs, integrations, or to do something on Airwallex, explicitly mention "Airwallex" in your prompt. This helps the model select the appropriate Airwallex tools, connector, and skill.

Examples:

Integrate Airwallex's Drop-in Element with this website.
Using Airwallex, can you find me test card numbers for the 3D Secure (3DS) authentication failure case?
Using Airwallex, list my USD and EUR balances across all global accounts.
Using Airwallex, create a beneficiary from this supplier onboarding PDF.
Using Airwallex, issue a virtual card for our new hire with a $2,000 monthly limit.

Clarify your business and technical context

Providing context upfront helps the model return more targeted, accurate responses. Include the following in your prompt where relevant:

What you're building or the task you want completed: for example, online payments (HPP or Embedded Elements), payouts, issuing, or billing subscriptions, and the resources involved.
Your tech stack: for example, React, Node.js, Java, or PHP.
Your environment: sandbox or production. Note that Developer MCP sandbox tools only operate in the sandbox environment.
Any constraints: currencies, limits, or accounts.

Use plan mode for write actions

Enable plan mode for complex tasks and any task that creates or modifies resources. This lets you review the agent's planned actions before execution, so you understand and approve each step.

Review before you commit

AgentOS does not initiate money-out actions on your behalf by default, and CLI write actions require confirmation unless --confirm is passed. Always review generated configurations and resources before approving them on a production account.

Connect Developer MCP for sandbox testing

Authorize the Developer MCP with your sandbox account so the agent can create test resources and simulate events. With Developer MCP connected, the agent can:

Create test transactions and billing plans.
Simulate transfer status updates.
Generate payment links for testing.
Interact with your sandbox account directly.

This enables end-to-end development and testing workflows without leaving your coding environment.

Example:

Can you create a new billing plan on Airwallex called Startup for $29.99/month and create a hosted URL to subscribe to it?

Troubleshoot common issues

This error occurs when the OAuth token used by the Developer MCP remote endpoint has expired or was not completed.

Re-run the one-click installation or OAuth flow for your tool.
Complete the authorization within a few minutes of starting the flow — tokens expire quickly.
Confirm you are authorizing with the sandbox account you intend to use.

AgentOS: CLI authentication is failing

Confirm you authenticated against the right environment — use airwallex auth login --prod for production.
Run airwallex auth whoami to check which environment you're signed in to.
Only users with the Owner, Admin, or Finance Admin role can complete the OAuth flow. See Who can install.

AgentOS: a Card or Issuing command returns a 403

Card and Issuing commands require additional permissions. Contact Customer Support to enable access for your account.

Troubleshoot an API error

Paste the error message directly into your AI assistant and ask it to help diagnose the issue. For example:

Using Airwallex, I got this error when creating a payment intent: [error message]. Please help me troubleshoot.

The assistant will use Airwallex documentation and the request context to provide troubleshooting steps.