Skip to main content
Use @spfunctions/agent when your TypeScript app owns the agent loop and needs SimpleFunctions market context, strict tools, watch inputs, policy hooks, trace, replay, and guarded execution.

​
1. Install

npm init -y
npm install @spfunctions/sdk@1.0.1 @spfunctions/agent@1.0.2

​
2. Set keys

export SF_API_KEY="sf_..."
export OPENROUTER_API_KEY="..."
SF_API_KEY is for SimpleFunctions data and user-scoped reads. OPENROUTER_API_KEY is only needed for model-backed runs.

​
3. Run the first agent

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 Kalshi market moves.")

for await (const event of run.stream()) {
  console.log(event.type)
}
Read-only SimpleFunctions strict tools are mounted by default. Write and execution tools are opt-in.

​
4. Restrict tools and cost

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,
    maxTokens: 1024,
  }),
  model: { id: "anthropic/claude-haiku-4.5" },
  builtinTools: ["world.read", "markets.search", "market.inspect", "market.candles"],
  options: {
    maxTurns: 4,
    maxBudgetUsd: 0.50,
    maxOutputTokens: 768,
    allowedTools: ["world.read", "markets.search", "market.inspect", "market.candles"],
    canUseTool(toolName, input) {
      if (toolName === "markets.search" && input && typeof input === "object") {
        return { behavior: "allow", updatedInput: { ...input, limit: 5 } }
      }
      return { behavior: "allow" }
    },
  },
})
Use canUseTool to shrink expensive searches, deny unexpected tickers, or require human confirmation before side effects.

​
5. Add watch inputs

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

for await (const tick of watch.ticks({
  tickers: ["KXEXAMPLE"],
  cadence: "5min",
  cycles: 1,
})) {
  console.log(tick.ticker, tick.price, tick.delta)
}

​
6. Keep execution policy-gated

Live execution is not mounted by default. Use the low-level SimpleFunctionsAgent with explicit side-effect, cost, venue, ticker/token, quantity, price, runtime, jurisdiction, and confirm-token guardrails when you need it. 
import { SimpleFunctions } from "@spfunctions/sdk"
import { SimpleFunctionsAgent } from "@spfunctions/agent"

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

const executionAgent = new SimpleFunctionsAgent({
  client: sf,
  policy: {
    maxSideEffect: "live_trade",
    maxCostEffect: "venue_request_cost",
    trade: {
      allowedVenues: ["polymarket"],
      blockedJurisdictions: ["US", "FR"],
      requireJurisdiction: true,
      maxQuantity: 1,
      maxOrderCostCents: 100,
      requireLimitPrice: true,
      allowRuntimeStart: true,
    },
  },
})

await executionAgent.tools.execution.place({
  venue: "polymarket",
  tokenId: "POLYMARKET_CLOB_TOKEN_ID",
  action: "buy",
  quantity: 1,
  limitPrice: 32,
  jurisdiction: "CA",
  confirm: process.env.SF_TRADE_CONFIRM,
})

​
Next steps

Agent SDK

Full Agent SDK surface and boundaries.

Agent market monitor cookbook

Build a read-only monitoring agent.

Agent trader loop cookbook

Combine quant gates, model notes, and execution policy.

Contract tools

Strict SDK and Agent tool manifest.