somnia-agents-invoke

Invoke a Somnia Agent

Fire a one-off createRequest against SomniaAgents from a wallet, wait for the on-chain finalisation, and decode the result. Useful for testing agents end-to-end and for scripting agent calls without deploying a wrapper contract.

Read the master somnia-agents skill first if you don't already understand the request lifecycle and gas model.

Network & Agent Reference

!cat references/network-config.json

!cat references/agents.json

The 3 base agents share the same agentId on Mainnet and Testnet. Per-agent prices come from the pricePerAgent field above (whole tokens — SOMI on Mainnet, STT on Testnet).

Prerequisites

• PRIVATE_KEY set to a funded wallet (hex, with or without 0x). Use agentExplorerUrl from the network config to verify and the faucet for testnet.
• Node ≥ 18 and npm install run at the repo root (so viem / zod are available via the workspace).
• cast (Foundry) optional — used for some quick sanity checks below.

Steps

1. Pick the agent and method

Browse the Agent Explorer (agentExplorerUrl) or look at references/agents.json. You need:

• Agent slug: json-fetch, llm-inference, or llm-parse-website (this maps to agentId automatically)
• Function name: e.g. fetchUint, inferString, ExtractString
• Arguments: positional, in the order declared in the agent's ABI

2. Send the request

scripts/invoke.ts builds the payload, sizes the deposit, and submits the transaction. It defaults to testnet and the platform-default subcommittee (Majority consensus, size 3, 15-minute timeout). Pass JSON-encoded args.

# Fetch the BTC/USD price as uint256 (8 decimals)
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent json-fetch --function fetchUint \
  --args '["https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd","bitcoin.usd",8]'

# Single-turn LLM classification with allowed values
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent llm-inference --function inferString \
  --args '["Classify: I love this product!", "You are a sentiment classifier. Reply with one word.", false, ["positive","negative","neutral"]]'

# Web extraction in direct mode
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent llm-parse-website --function ExtractString \
  --args '["best_drama","Title of the film that won Best Motion Picture - Drama.",[],"Best Picture winners at the 2026 Golden Globe Awards","goldenglobes.com",true,3]'

# Custom subcommittee (Threshold consensus, 5 validators, 3-of-5)
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent json-fetch --function fetchUint \
  --args '["https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd","ethereum.usd",8]' \
  --subcommittee-size 5 --threshold 3 --consensus threshold --timeout 60

# Mainnet
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --network mainnet --agent json-fetch --function fetchUint \
  --args '[...]'

The script prints the requestId, the deposit it sent, and the transaction hash — and by default polls for finalisation. Pass --no-wait to fire and return immediately.

3. Wait for finalisation (separately)

If you fired with --no-wait, or you already have a requestId from another source:

npx tsx skills/somnia-agents-invoke/scripts/wait-response.ts \
  --request-id 12345 --agent json-fetch

This subscribes to RequestFinalized, then reads getRequest(requestId) and ABI-decodes responses[0].result against the agent's return type. Pass the same --agent you used to invoke so the script knows which return type to decode.

4. Read the off-chain receipt

The full step-by-step audit trail (HTTP calls, LLM reasoning, errors) lives off-chain. The receipts service is two-tier:

1. Index endpoint (/agent-receipts?contractAddress=<addr>&requestId=<id>) returns a list of GCS URLs — one per validator that submitted a receipt.
2. Each GCS URL contains the actual receipt JSON.

The script fetches both tiers and prints a concise per-validator summary by default:

# All validators, summary
npx tsx skills/somnia-agents-invoke/scripts/read-receipt.ts --request-id 12345

# Only the first validator (0-indexed), full JSON
npx tsx skills/somnia-agents-invoke/scripts/read-receipt.ts --request-id 12345 --validator 0 --raw

# Just the index (list of GCS URLs)
npx tsx skills/somnia-agents-invoke/scripts/read-receipt.ts --request-id 12345 --index

Or directly via curl:

# 1. Get the GCS URL list
curl -s "https://receipts.testnet.agents.somnia.host/agent-receipts?contractAddress=0x037Bb9C718F3f7fe5eCBDB0b600D607b52706776&requestId=12345" | jq

# 2. Fetch one of the receipts
curl -s "<gcs-url-from-step-1>" | jq

Environment Variables

Variable	Required	Description
PRIVATE_KEY	Yes (for invoke.ts)	Funded wallet private key (hex, with or without 0x prefix)
SOMNIA_AGENTS_NETWORK	No	Default network when --network is omitted: testnet (default) or mainnet

CLI Flags — invoke.ts

Flag	Required	Description
--agent <slug>	Yes (or --agent-id)	One of: json-fetch, llm-inference, llm-parse-website
--agent-id <uint>	Yes (or --agent)	Raw agentId (use when invoking an agent not listed in agents.json)
--function <name>	Yes	Function name from the agent's ABI
--args <json>	Yes	JSON-encoded array of positional args, e.g. '["url","selector",8]'
--network <name>	No	testnet (default) or mainnet
--subcommittee-size <int>	No	Default 3. Sizes >3 use createAdvancedRequest.
--threshold <int>	No	Required if --subcommittee-size or --consensus set. ≤ subcommittee size.
--consensus <name>	No	majority (default) or threshold
--timeout <secs>	No	Default 900 (15 min) when using createAdvancedRequest
--price-per-agent <decimal>	No	Override the per-agent price (defaults to agents.json value)
--callback <addr>	No	Callback contract. Default 0x0000…0000 (no callback — script polls for finalisation directly)
--callback-selector <hex>	No	4-byte selector. Default 0x00000000.
--no-wait	No	Print requestId + tx hash and exit; don't wait for finalisation
--gas-limit <uint>	No	Override gas limit. Default 2_000_000.

CLI Flags — wait-response.ts

Flag	Required	Description
--request-id <uint>	Yes	Request ID returned by invoke.ts
--agent <slug>	Yes (or --agent-id + --function)	Used to look up the return type for decoding
--function <name>	Sometimes	Required when only --agent-id is provided
--network <name>	No	testnet (default) or mainnet
--from-block <uint>	No	Block to start scanning for RequestFinalized events. Default: latest − 12000 (best-effort window). Pass the createRequest block for older requests.
--timeout <secs>	No	How long to wait for finalisation. Default 1200 (20 min).

Why event-watching, not state polling? The platform contract zeros out the request slot at finalization, so a post-finalize getRequest(requestId) reverts with RequestNotFound. The script watches for the RequestFinalized event and reads state from the block before finalization, which still has the populated slot.

CLI Flags — read-receipt.ts

Flag	Required	Description
--request-id <uint>	Yes	Request ID
--network <name>	No	testnet (default) or mainnet
--contract <addr>	No	Override the contract address used in the index lookup (default: SomniaAgents from network config)
--validator <int>	No	Print only the receipt at this 0-indexed validator slot (default: all)
--index	No	Print only the index endpoint response (the list of GCS URLs), don't fetch each receipt
--raw	No	Print receipt JSON unmodified (default: pretty-print key fields)

Patterns

Pure exploration — fire and check

# Fire it
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent json-fetch --function fetchUint \
  --args '["https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd","bitcoin.usd",8]'
# → requestId: 12345, deposit: 0.12 STT, txHash: 0x...
# Script then polls for finalisation and prints the decoded uint256

Scripted — fire, branch on result

RESULT=$(npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent json-fetch --function fetchBool \
  --args '["https://api.example.com/market/status","isOpen"]' --json)
echo $RESULT | jq -e '.status == "Success" and .decoded == true' >/dev/null && echo "Market open"

--json (added implicitly by passing the flag below) writes a single JSON line with {requestId, txHash, status, decoded} for easy jq consumption.

Async — fire now, check later

# Submit and exit immediately
ID=$(npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --no-wait --agent llm-parse-website --function ExtractString \
  --args '[...]' --json | jq -r '.requestId')

# ... later ...
npx tsx skills/somnia-agents-invoke/scripts/wait-response.ts --request-id "$ID" --agent llm-parse-website

Common Errors

Symptom	Likely cause	Fix
InsufficientDeposit(sent, required)	Custom subcommitteeSize without enough reserve	Let the script compute deposit, or pass --price-per-agent matching the agent type
Status TimedOut, no responses	Floor-only deposit (perAgentBudget = 0)	Ensure the per-agent price reaches runners. Don't override with --price-per-agent 0.
Status Failed immediately	Agent execution itself failed	Read the receipt — read-receipt.ts --request-id <id>. Often a 4xx/5xx on the upstream URL.
wait-response.ts times out	Test/staging runner congestion or LLM cold-start	Increase --timeout. Check the receipt — if no validator submitted, raise the per-agent price.
Decoding error in wait-response.ts	Wrong --agent / --function for the request	Pass the exact agent + function used during invoke.ts.

Source

• scripts/invoke.ts — builds payload, sizes deposit, submits transaction, optionally waits
• scripts/wait-response.ts — polls RequestFinalized, decodes result against the agent ABI
• scripts/read-receipt.ts — fetches off-chain receipt JSON

All three load network + agent config from references/ at the repo root.