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.
Leverage sandbox credentials with Developer MCP
Configure your sandbox API credentials to unlock additional Developer MCP tools for testing and simulation. With sandbox credentials, 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?
Review available developer connectors MCP tools
The developer connectors MCP servers expose different tools depending on which one you connect to:
| Tool category | Developer MCP | Docs MCP |
|---|---|---|
| Documentation tools | ||
| Sandbox tools |
For production reads and writes, use the Airwallex CLI or Airwallex AgentOS MCP.
Documentation tools
Available on: Developer MCP, and Docs MCP.
| Name | Description |
|---|---|
search_public_docs | Search the Airwallex documentation. Covers the following sources: Product docs, API reference API, Airwallex.js JS, Payments iOS and Android SDKs |
read_integration_best_practices | Read Airwallex integration best practices. This tool provides essential guidelines for API usage, payment handling, SDK implementation, and common pitfalls to avoid. Called automatically before code generation tasks. |
Sandbox tools
Available on: Developer MCP.
All data retrieved and actions performed with the tools below are in the authenticated sandbox account.
Core resources
| Name | Description |
|---|---|
list_global_accounts | List all available global accounts |
get_balances | List balances in all currencies |
list_deposits | List all deposits |
simulate_create_deposit | Simulate a deposit to an available global account |
list_linked_accounts | List all linked accounts |
create_linked_account | Create a linked account with mandate for direct debit (supports AU, CA, EU, GB, NZ, US banks) |
verify_micro_deposits | Confirm the linked bank account is usable and owned by the user: submit the micro-deposit amounts credited to that account. In sandbox, use values such as 0.01 and 0.02. |
simulate_mandate_operation | Simulate direct debit mandate status transitions (only needed for GB bank) |
list_direct_debits | List all direct debit transactions |
create_direct_debit_deposit | Create a direct debit deposit to pull funds from a verified linked account |
Transactional FX
| Name | Description |
|---|---|
get_fx_rate | Get current foreign exchange rate for a currency pair |
create_fx_quote | Create a foreign exchange quote for a currency conversion |
Payouts
| Name | Description |
|---|---|
list_transfers | List transfers initiated |
create_transfer | Initiate a new transfer to a recipient |
simulate_transfer_result | Simulate the status of a transfer |
list_beneficiaries | List available transfer recipients |
Payment Acceptance
| Name | Description |
|---|---|
list_payment_customers | List all payment customers |
create_payment_customer | Create a payment customer |
list_payment_intents | List all payment intents |
create_payment_link | Create a new payment link |
list_payment_links | List created payment links |
list_payment_consents | List all payment consents |
list_refunds | List all refunds |
create_refund | Create a refund against a PaymentIntent or PaymentAttempt |
list_payment_disputes | List all payment disputes |
simulate_create_payment_dispute | Simulate creating a payment dispute for testing dispute handling |
accept_payment_dispute | Accept a payment dispute |
challenge_payment_dispute | Challenge a payment dispute by providing reason and evidence |
simulate_escalate_payment_dispute | Simulate escalating dispute to next stage |
simulate_resolve_payment_dispute | Simulate issuing bank's final decision |
Issuing
| Name | Description |
|---|---|
list_cardholders | List all cardholders |
create_cardholder | Create a cardholder |
list_cards | List all issued cards |
create_card | Create a card with authorization controls and spending limits |
list_issuing_transactions | List all card transactions |
simulate_create_issuing_transaction | Simulate a card transaction |
simulate_capture_issuing_transaction | Simulate capturing a pending authorization transaction |
simulate_reverse_issuing_transaction | Simulate reversing a pending authorization transaction |
simulate_refund_issuing_transaction | Simulate refunding a captured card transaction |
Billing
| Name | Description |
|---|---|
list_billing_products | List available billing products |
list_billing_prices | List available billing prices |
create_billing_product | Create a new billing product |
create_billing_price | Create a new billing price |
create_billing_checkout | Create a new hosted billing checkout page |
Troubleshoot common issues
Developer connectors: "Invalid or expired consent token" error
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 --prodfor production. - Run
airwallex auth whoamito 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.
See also
- Developer connectors — docs and sandbox MCP servers for building and testing.
- AgentOS — production-grade toolkit for acting on your production account.
- Airwallex CLI — the production connector AgentOS is built on.
- Skills — pre-built workflows for common Airwallex tasks.