Skip to main content
This page documents the first experimental SDK/agent vertical slice: 
world.read -> GET /api/agent/world?format=json -> sf world --json -> sf.world.get()
It is read-only. It does not place trades, create paper orders, mutate portfolio state, create theses, start daemons, or expand MCP.

​
Status

@spfunctions/sdk is published as a stable package: 
npm install @spfunctions/sdk@1.0.1
Use the stable package version.

​
API

GET /api/agent/world?format=json
The endpoint returns the current salience-ranked SimpleFunctions world state. The current schema is conservative because the endpoint still includes the SPEC-10 snapshot shape plus legacy aliases for older consumers. Stable fields to expect when present:
  • asOf
  • servedAt
  • op
  • region
  • regime
  • salient
  • childRegions
  • marketCount

​
CLI

sf world --json
The CLI is the first-class surface. It calls the same world endpoint and requests JSON when --json is present.

​
SDK

import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  apiKey: process.env.SF_API_KEY,
  baseUrl: process.env.SF_API_URL,
})

const world = await sf.world.get()

console.log(world.asOf)
console.log(world.salient?.slice(0, 3))
world.read is read-only (sideEffect: "none") but it is a hosted data call with costEffect: "api_cost" and access.anonymousAllowed: false. The SDK therefore requires SF_API_KEY for sf.world.get(). No-key SDK bootstrap is limited to strict manifest inspection such as sf.manifest.get("world.read"). If apiKey is present, the SDK sends it as a bearer token. The SDK does not shell out to the CLI, call an LLM, retry hidden mutations, or perform side effects.

​
Agent Tool

The agent metadata exposes the canonical tool as world.read. Tool hosts that reject dotted identifiers can use the compatibility name world_read. 
{
  "name": "world.read",
  "compatName": "world_read",
  "permissions": ["read.public", "market_data", "read"],
  "sideEffect": "none",
  "costEffect": "api_cost",
  "access": { "anonymousAllowed": false },
  "authRequired": false,
  "schema": "WorldState",
  "sdk": "sf.world.get()",
  "http": "GET /api/agent/world?format=json",
  "cli": "sf world --json"
}

​
Direct Agent Tool Events

The first accepted event stream supported only world.read. The current direct tool once-mode also supports additional read/research tools from the draft contract map. 
sf agent --tool world.read --stream-json
sf agent --tool markets.search --stream-json --input '{"query":"Fed CPI","limit":5}'
--ndjson is an alias for --stream-json. Minimum emitted event types:
  • session.init
  • tool.catalog.loaded
  • run.started
  • tool.call.started
  • tool.call.completed or tool.call.failed
  • agent.final
  • run.completed

​
Trace

Use a local trace file when you need an audit receipt: 
sf agent --tool world.read --stream-json --record-trace trace.ndjson
sf trace receipt trace.ndjson --json
The trace entry stores the tool name, empty input, compact output summary, error if any, and duration. It must not store API keys, bearer tokens, venue credentials, or trading secrets.

​
Contract Map

The draft contract map entry lives at: 
contracts/sf-contract-map.draft.json
The draft now includes the read/research SDK and Agent contract slices plus deferred entries for surfaces that do not yet have safe canonical endpoints.