Run your first agent

Run two simulated payments, predict which one the policy refuses, and inspect
both decisions in Axorum Console. Your agent and sandbox run locally. No money
moves to a payment provider.

This walkthrough uses Node.js 22 or later and pnpm. It targets
@axorum/sandbox 0.4.2 and @axorum/client 1.2.1. The sandbox version is the
same on npm and PyPI; the agent client has its own version sequence. These are
the versions verified for this guide, not a claim about future registry releases.

1. Start in an empty directory

shell

1mkdir axorum-first-agent
2cd axorum-first-agent
3pnpm init
4pnpm add @axorum/[email protected] @axorum/[email protected]
5pnpm exec axorum-sandbox --version
6

Keep the generated lockfile. You do not need TypeScript tooling: the script
below is a JavaScript module that uses the TypeScript client's published package.

2. Choose the sample in the console

Sign in to Axorum Console, create an
organization if needed, and create a sandbox using the agent-payments sample.
This sample allows approved vendors and caps total payments to OpenAI at $20.

Keep the sample unchanged for this walkthrough. It already binds the buyer
agent and opens the USD spend/payable accounts used by the client's default
chart. You do not need to invent account IDs or create credentials for an
unrelated agent.

3. Connect your local sandbox

Issue the sandbox's secret and copy the console's two environment exports into
your terminal. AXORUM_SANDBOX_SINK must be
https://console.beta.axorum.com; AXORUM_SANDBOX_TOKEN is the issued axsb_…
secret. Keep it private and out of your source files.

In that terminal, fetch the selected world and its policy, then start it:

shell

1pnpm exec axorum-sandbox pull --output world.yaml
2pnpm exec axorum-sandbox serve world.yaml
3

Leave this terminal running. It should report the agent-payments world at
http://127.0.0.1:7340. If that port is occupied, stop the earlier sandbox before
continuing. A fresh process starts a fresh run with no earlier OpenAI spend.

4. Run a complete agent script

Open a second terminal in the same project directory. Save the following as
agent.mjs. The token callback asks the running sandbox for the identity that
the sample already binds; it does not use your console login or sandbox secret.

javascript

1import { execFileSync } from 'node:child_process'
2import { Agent, AxorumClient, payment } from '@axorum/client'
3import { binary } from '@axorum/sandbox/native'
4
5const url = 'http://127.0.0.1:7340'
6const buyer = 'agent://example.com/agent/buyer_01h455vb4pex5vsknk084sn02q'
7const token = () => execFileSync(binary(), [
8  'token', '--url', url, buyer,
9], { encoding: 'utf8' }).trim()
10const agent = new Agent(buyer, token)
11const axorum = new AxorumClient({ baseUrl: url })
12
13for (const [minor, justification] of [
14  [1500n, 'Simulate the first $15 API purchase within the approved vendor budget'],
15  [1000n, 'Test whether a second $10 API purchase exceeds the $20 vendor limit'],
16]) {
17  const request = payment({
18    amount: { minor, currency: 'USD' },
19    payee: 'api.openai.com',
20    justification,
21  })
22  const answer = await axorum.authorize(agent, request)
23  console.log(request.transaction, answer.allowed ? 'allowed' : 'refused')
24  if (!answer.allowed) {
25    console.log(answer.refusal.rule?.name ?? answer.refusal.code)
26    console.log(answer.refusal.explanation)
27  }
28}
29

Predict the result before running it: $15 is allowed; another $10 would make
the total $25, so the policy refuses it. minor is cents in this world's USD
configuration. Run the script once:

shell

1node agent.mjs
2

Expect one allowed and one refused, each with a transaction ID. The client
may also warn that one endpoint is configured; this walkthrough intentionally
uses one local sandbox. A refusal
is a recorded policy verdict, not a failed HTTP request. Do not retry it hoping
for approval. If a request has an uncertain transport outcome, retain its
request and transaction ID rather than minting a new payment for the same action.

5. Inspect both decisions

Return to the sandbox in the console and open its latest run. Find the two
transaction IDs printed by the script. Inspect the approval and the refusal;
the latter should name forbid_over_payee_limit. The refused payment does not
increase posted spend. If no run appears, check the first terminal's reporting
errors and confirm both environment variables were set before serve started.

6. Save and replay the run

While the first terminal is still serving, save its run from the second:

shell

1pnpm exec axorum-sandbox save-run --output first-agent.scenario.yaml
2pnpm exec axorum-sandbox run first-agent.scenario.yaml --offline
3

Expect one matched scenario and no divergence. The saved file includes the
world, policy and recorded steps; replay needs no console credential. The run
page also offers Save as scenario to retain it in your organization's
scenario library. You can stop the serving terminal with Ctrl-C afterwards.

For deeper questions, use the sandbox reference,
SDK reference and
agent skills.