SDK World State Pattern

When to use

• Long-running TypeScript service that needs current market context
• Agent runtime that wants compact world state on each turn
• Custom dashboard or monitor that needs the SF salience ranking

Prerequisites

npm install @spfunctions/[email protected] @spfunctions/[email protected]
export SF_API_KEY="sf_..."

world.read is cost-bearing and requires SF_API_KEY.

Contract mapping

world.read → GET /api/agent/world?format=json → sf world --json → sf.world.get()

Snapshot pattern

import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  apiKey: process.env.SF_API_KEY,
  baseUrl: process.env.SF_API_URL ?? "https://simplefunctions.dev",
})

const world = await sf.world.get()

console.log(world.asOf)
console.log(world.regime?.label)
console.log(world.salient?.slice(0, 5).map(item => ({
  type: item.type,
  ticker: item.ticker,
  label: item.label,
})))

Stable fields when present: asOf, servedAt, op, region, regime, salient, childRegions, marketCount.

Delta pattern (for long-running agents)

Use deltas when a long-running agent only needs changes since its last run:

// CLI equivalent: sf world --delta --json --since 1h
const deltaResponse = await fetch(
  `https://simplefunctions.dev/api/agent/world/delta?since=1h`,
  { headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}` } }
)
const delta = await deltaResponse.json()

console.log(delta.added)   // new salient items
console.log(delta.removed) // items dropped from salience
console.log(delta.changed) // items with material price/indicator changes

Typical delta payload is 30-50 tokens vs. 800+ for full snapshot. Use deltas inside agent loops; use snapshots on cold start.

Watch pattern (semi-realtime stream)

import { watch } from "@spfunctions/agent/v1"

for await (const tick of watch.world({
  cadence: "5min",
  cycles: 12, // 1 hour
})) {
  console.log(tick.asOf, tick.regime?.label, tick.salient?.length)
}

watch.world() yields snapshots at the cadence. Each tick is a fresh world state.

For ticker-specific watch:

for await (const tick of watch.ticks({
  tickers: ["KXFED-27APR-T3.50", "KXCPIYOY-26JUN-T4.2"],
  cadence: "5min",
  cycles: 1,
})) {
  console.log(tick.ticker, tick.price, tick.delta)
}

Combining with an agent loop

import { Agent, OpenRouterProvider } from "@spfunctions/agent/v1"

const agent = await Agent.create({
  apiKey: process.env.SF_API_KEY,
  provider: new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY }),
  model: { id: "anthropic/claude-haiku-4.5" },
  builtinTools: ["world.read"],
  options: {
    watch: [
      { kind: "world", cadence: "5min" },
    ],
    maxTurns: 4,
    maxBudgetUsd: 0.50,
  },
})

const run = agent.send("Watch world state. Summarize each material change.")

for await (const event of run.stream()) {
  if (event.type === "agent.final") {
    console.log(event.output)
  }
}

This pattern: the watch primitive feeds fresh world snapshots into the agent's context at each tick, and the agent's LLM summarizes the changes.

Tool metadata

{
  "name": "world.read",
  "compatName": "world_read",
  "permissions": ["read.public", "market_data", "read"],
  "sideEffect": "none",
  "costEffect": "api_cost",
  "access": { "anonymousAllowed": false },
  "schema": "WorldState",
  "sdk": "sf.world.get()",
  "http": "GET /api/agent/world?format=json",
  "cli": "sf world --json"
}

sideEffect: "none" = no state mutation. costEffect: "api_cost" = bills a small HTTP fetch cost. anonymousAllowed: false = requires SF API key.

Errors

• `MissingApiKeyError`: set SF_API_KEY. Browsing the manifest works without key; reading data does not.
• `HttpError 401`: API key invalid or revoked. Generate a new one in the dashboard.
• `HttpError 429`: rate limited. Back off. Free-tier limits are documented at <https://docs.simplefunctions.dev/enterprise/rate-limits>.

Related skills

• sf-sdk-quickstart — install + first call (run this first)
• sf-sdk-market-research — markets.search + market.inspect patterns
• sf-agent-sdk-quickstart — Agent.create loop

Reference docs

• <https://docs.simplefunctions.dev/guides/world-read-sdk>
• <https://docs.simplefunctions.dev/api-reference/world-state>