Python integration · Standard library

Your Python agent.
One small client.

Discover contracts for free, then call a tool with an explicit maximum price. Use Python 3.10 or newer; no pip install, Node runtime or MCP process is required.

Download Python client Download example

Client checksum · Example checksum · Full instructions · MIT license · GitHub files

Preview before paying

Save the client and example in the same folder, verify their checksums, then run the default example. It prepares a barcode request offline. It does not execute a tool, contact the service or require a key.

shasum -a 256 -c agent_utilities.py.sha256
shasum -a 256 -c agent_utilities_example.py.sha256
python3 agent_utilities_example.py

Add --discover to read public schemas, prices and documentation without a key or charge.

Try a shopping scenario

Explore the cheapest pack mix, limited stock and insufficient stock with three fixed examples. Save the pack-planning script and sample cases beside the Python client. Verify the script checksum and data checksum.

python3 pack_plan_example.py
python3 pack_plan_example.py --scenario limited-stock
python3 pack_plan_example.py --scenario insufficient-stock

Preview prints fixed inputs and expected answers offline; it does not compute a new plan or contact the service. Add --execute only to authorize one call using existing credits, capped at $0.0008. A valid infeasible result is billable. Retain the printed request ID and exact input before execution; a new run creates a new billable identity.

Read the pack-planning workflow · Full instructions and recovery

Compare delivered checkout totals

An $18 item can cost more at checkout than a $22 item after shipping and discounts. Supply 2–10 comparable carts in one currency; the recipe reconciles each, ranks complete totals and keeps missing costs visible. Any incomplete candidate prevents an overall winner.

Download comparison recipe Sample checkout snapshots

Keep both files beside the Python client. Verify the script checksum and input checksum, then preview offline:

python3 compare_carts.py

Preview validates inputs and prints the planned requests; it does not calculate totals or contact the service. The fictional sample totals are $25.49 and $22.50. Use --input your-carts.json to prepare your own snapshots. Add --execute only to authorize paid calls with existing credits: $0.0005 maximum per cart, with a default total cap of $0.001 for two carts. More carts need an explicit total ceiling.

Retain the printed plan privately before execution. New runs create new billable IDs; recover an uncertain call using its original input and ID. Earlier successful calls remain charged if a later call fails. Full input, budget and recovery instructions.

Give each call a ceiling

When you have a useful task, create and save credentials in the workspace and add prepaid credits. Set only your API key privately in the process environment. The example below authorizes at most $0.0003 for a new call.

from agent_utilities import Client, prepare_call
import os

client = Client(os.environ['AGENT_UTILITIES_API_KEY'])
call = prepare_call(
    'commerce.gtin-validate',
    {'code': '036000291452'},
    max_price_micro_usd=300,
)
# Retain call before sending. Reuse it after a lost response.
response = client.execute(call)

Preparing a call makes no HTTP request. Execution checks payment mode and price-limit support, then sends the frozen input, request ID and ceiling. If the price exceeds your limit, the server rejects the new reservation before a debit. The client never purchases credits or increases a ceiling automatically.

Keep the original call for recovery

The client retries an uncertain HTTP exchange once with the same input, ID and ceiling. If uncertainty remains, its CallError.call preserves the prepared operation. Use client.execute(call) again within ten minutes after resolving the error. Do not create a new call to retry: a new ID is a new billable operation.

For recovery after a process restart, your application must privately preserve the original ID, tool, input and ceiling before sending. The library does not write a disk journal. A zero ceiling allows recovery of an existing reservation without authorizing a new one; it does not undo previous spending.