> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent SDK quickstart

> Install @spfunctions/agent and run the first Cursor-style market-intelligence agent with strict SimpleFunctions tools.

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

```bash theme={null}
npm init -y
npm install @spfunctions/sdk@1.0.1 @spfunctions/agent@1.0.2
```

## 2. Set keys

```bash theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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.

```ts theme={null}
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

<CardGroup cols={2}>
  <Card title="Agent SDK" href="/agent-sdk">
    Full Agent SDK surface and boundaries.
  </Card>

  <Card title="Agent market monitor cookbook" href="/cookbook/agent-market-monitor">
    Build a read-only monitoring agent.
  </Card>

  <Card title="Agent trader loop cookbook" href="/cookbook/agent-trader-loop">
    Combine quant gates, model notes, and execution policy.
  </Card>

  <Card title="Contract tools" href="/api-reference/contract-tools">
    Strict SDK and Agent tool manifest.
  </Card>
</CardGroup>