SimpleFunctions SDK + Agent SDK Quickstart

When to use

• Starting a new TypeScript project that needs SimpleFunctions data
• First-time setup before writing any SDK code
• Migrating from CLI-based scripts to SDK-based runtime

Prerequisites

• Node 18 or newer
• TypeScript 5+ (recommended)
• (For data calls) SimpleFunctions API key: <https://simplefunctions.dev/settings/api-keys>
• (For agent runs) OpenRouter API key: <https://openrouter.ai/keys>

Step 1: Install

npm init -y
npm install @spfunctions/[email protected] @spfunctions/[email protected]

Pin the alpha versions. These packages are published for early builders, not GA. Without pinning, your install may pull a breaking change.

Step 2: Set environment variables

export SF_API_KEY="sf_..."
export OPENROUTER_API_KEY="sk-or-..."

For server-side use only. Do not put long-lived keys in browser bundles.

Step 3: Inspect the strict contract (no key required)

/api/contracts/tools is the SDK and Agent contract truth — what tools exist, what their permissions are, what their cost class is.

import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  baseUrl: "https://simplefunctions.dev",
})

const manifest = await sf.manifest.list()
const world = await sf.manifest.get("world.read")
const legacy = await sf.manifest.get("get_world_state")

console.log(manifest.schemaVersion) // "0.3.0-draft"
console.log(world?.name)            // "world.read"
console.log(legacy)                 // null — broad compat name, not canonical

The contract manifest works without an API key. Use it to discover available tools before writing code that calls them.

Step 4: First authenticated SDK data call

import { SimpleFunctions } from "@spfunctions/sdk"

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

const world = await sf.world.get()

console.log(world.asOf)
console.log(world.regime?.label)
console.log(world.salient?.slice(0, 3).map(item => item.label))

If SF_API_KEY is not set, this throws MissingApiKeyError — world.read is cost-bearing (costEffect: "api_cost") and not anonymously allowlisted.

Step 5: First Agent.create() loop

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

const agent = await Agent.create({
  apiKey: process.env.SF_API_KEY,
  openRouterApiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "anthropic/claude-haiku-4.5" },
})

const run = agent.send("Read world state and summarize the largest market moves.")

for await (const event of run.stream()) {
  console.log(event.type)
}

// Resume a run from another process:
const sameRun = await Agent.getRun(run.id, { agentId: run.agentId })
await sameRun?.wait()

Agent.create({ apiKey }) mounts read-only SimpleFunctions strict tools by default. Write tools are opt-in only — pass builtinTools: "all" or a named allowlist to mount them.

Step 6: Verify

Run the script:

npx tsx your-script.ts

Expected:

• Manifest call returns schema version "0.3.0-draft"
• World call returns an object with asOf, regime.label, and a populated salient array
• Agent run streams events: agent.run.started, tool.call.started, tool.call.completed, agent.final, agent.run.completed

Common installation issues

• `Cannot find module '@spfunctions/sdk/v1'`: ensure the package is installed and node_modules exists. Some IDEs cache stale resolution — restart TypeScript server.
• `MissingApiKeyError` on every call: env var not loaded. In Node without dotenv, process.env.SF_API_KEY is undefined unless exported in shell.
• Type errors on `Agent.create()`: pin versions. The Agent SDK alpha has signature changes between minor versions.

Next steps

Pick a workflow:

Reference docs

• <https://docs.simplefunctions.dev/guides/sdk-agent-alpha-quickstart>
• <https://docs.simplefunctions.dev/guides/sdk-overview>
• <https://docs.simplefunctions.dev/agent-sdk>
• <https://docs.simplefunctions.dev/api-reference/contract-tools>