Build with AgentOS
Best practices, tools reference, and troubleshooting for AgentOS connectors and skills
To get the most out of AgentOS, follow the best practices below, choose the right connector for the task, and refer to the troubleshooting guidance if you encounter issues.
Choose the right connector for the task
AgentOS bundles four connectors. Pick based on what your agent needs to do:
- Documentation searches 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.
- 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.
- Production reads and writes from a chat UI or non-terminal agent — Production MCP (coming soon).
For the full positioning matrix, see Connectors.
Use skills for common 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.
Always mention "Airwallex" in your prompts
When asking your assistant about Airwallex products, APIs, or integrations, explicitly mention "Airwallex" in your prompt. This helps the model select the appropriate AgentOS connector and tools.
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?
- I tried to make a payout with Airwallex and got this error:
amount_below_transfer_method_limit. What does that mean?
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: for example, online payments (HPP or Embedded Elements), payouts, issuing, or billing subscriptions.
- 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.
Use plan mode
Enable plan mode for complex tasks. This allows you to review the agent's planned actions before execution, ensuring you understand and approve each step of the implementation.
If you're using Cursor, you can activate plan mode in either of the following ways:
- Select Plan from the agent mode dropdown in Cursor's composer.
- Mention it explicitly in your prompt (for example, "Using plan mode, help me integrate Airwallex Embedded Elements").
Be specific with your requirements
Provide detailed context about your use case, including the specific Airwallex product or feature you're working with, your preferred programming language and framework, the environment (sandbox or production), and any specific business requirements or constraints.
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 MCP tools
The MCP servers expose different tools depending on which one you connect to:
| Tool category | Developer MCP (remote) | Docs MCP | Developer MCP (local) |
|---|---|---|---|
| Documentation tools | |||
| Sandbox tools | |||
| Billing tools |
For production reads and writes, use the Airwallex CLI (or Production MCP, coming soon).
Documentation tools
Available on: Developer MCP (remote and local), 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 (remote and local).
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 tools
Available on: Developer MCP (local) only.
All data retrieved and actions performed with the tools below are in the authenticated sandbox account.
| 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
If you encounter problems connecting or authenticating, use the guidance below to diagnose and resolve them.
Sandbox API credentials are not working
- Confirm you are using credentials from the sandbox environment, not production.
- In Developer MCP local mode, verify that the
AIRWALLEX_SANDBOX_CLIENT_IDandAIRWALLEX_SANDBOX_API_KEYvalues in your MCP config are correct and have not been truncated.
"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.
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.