fourmis-agents-sdk

Multi-provider AI agent SDK with direct API access and in-process tool execution.

Requires Bun v1.0+. This SDK uses Bun-native APIs (Bun.spawn, Bun.Glob, Bun.build) and is not Node runtime-compatible for host execution.

What It Is

fourmis-agents-sdk provides a single query() API that works across providers while keeping the agent loop transparent and controllable.

• Multi-provider: Anthropic, OpenAI, Gemini (plus custom providers via registry)
• Claude-style message envelopes (system, assistant, user, stream_event, result)
• In-process tool execution (file/system/web/notebook/config/todo)
• Hooks, permissions, MCP servers, subagents, skills, and memory

Quick Start

import { query } from "fourmis-agents-sdk";

const conversation = query({
  prompt: "Read package.json and tell me the project name.",
  options: {
    provider: "anthropic",
    model: "claude-sonnet-4-5-20250929",
    cwd: process.cwd(),
    tools: { type: "preset", preset: "claude_code" },
    maxTurns: 5,
  },
});

for await (const msg of conversation) {
  if (msg.type === "assistant") {
    for (const block of msg.message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }

  if (msg.type === "result") {
    console.log(`\nstop=${msg.subtype} cost=$${msg.total_cost_usd.toFixed(4)}`);
  }
}

Providers

Built-in providers:

Provider	Auth
anthropic	ANTHROPIC_API_KEY or Claude OAuth token
openai	OPENAI_API_KEY or OpenAI/Codex OAuth
gemini	GEMINI_API_KEY or Gemini CLI OAuth

import { query, registerProvider } from "fourmis-agents-sdk";

query({ prompt: "...", options: { provider: "openai", model: "gpt-4.1-mini" } });
query({ prompt: "...", options: { provider: "gemini", model: "gemini-2.5-flash" } });

registerProvider("my-provider", myAdapter);

Tools

Current built-in tools:

Tool	Purpose
Bash	Shell command execution
Read	Read files with line numbers
Write	Write/overwrite files
Edit	Exact string replacement
Glob	File pattern matching
Grep	Regex content search
NotebookEdit	Edit Jupyter notebook cells
WebFetch	Fetch URL content
WebSearch	Lightweight web search
TodoWrite	Persist todo state
Config	Read/write .claude/settings*.json
AskUserQuestion	Ask user (returns runtime-unavailable error in this host mode)
ExitPlanMode	Request exit from plan mode

Tool configuration:

query({
  prompt: "...",
  options: {
    // Exposed preset
    tools: { type: "preset", preset: "claude_code" },

    // Or explicit list
    // tools: ["Read", "Glob", "Grep"],

    allowedTools: ["Read", "Glob", "Grep"],
    disallowedTools: ["Bash"],
  },
});

Hooks

Lifecycle hooks can observe and influence execution:

• PreToolUse, PostToolUse, PostToolUseFailure
• SessionStart, SessionEnd, Stop, Notification
• SubagentStart, SubagentStop, PreCompact, PermissionRequest
• UserPromptSubmit, Setup, TeammateIdle, TaskCompleted

query({
  prompt: "...",
  options: {
    hooks: {
      PreToolUse: [
        {
          matcher: "^Bash$",
          hooks: [
            async () => ({
              decision: { behavior: "deny", message: "Blocked by policy." },
            }),
          ],
        },
      ],
    },
  },
});

MCP (Model Context Protocol)

Supports stdio, sse, http, and in-process sdk MCP servers.

query({
  prompt: "...",
  options: {
    mcpServers: {
      stdioServer: { command: "node", args: ["server.js"] },
      remoteSse: { type: "sse", url: "http://localhost:3000/sse" },
      remoteHttp: { type: "http", url: "http://localhost:3000" },
      inProc: { type: "sdk", name: "my-tools", instance: myMcpServer },
    },
  },
});

Create in-process MCP server configs:

import { createMcpServer, mcpTool } from "fourmis-agents-sdk";
import { z } from "zod";

const mcpConfig = createMcpServer({
  name: "my-tools",
  tools: [
    mcpTool("greet", "Say hello", { name: z.string() }, async ({ name }) => {
      return `Hello, ${name}!`;
    }),
  ],
});

Subagents

Define agent roles and let the parent invoke them with Task:

query({
  prompt: "Delegate to researcher and report package name.",
  options: {
    agents: {
      researcher: {
        description: "Reads code and reports facts.",
        prompt: "Be concise and factual.",
        tools: ["Read", "Glob", "Grep"],
        maxTurns: 3,
      },
    },
  },
});

Permissions and Settings

Permission modes:

• default
• acceptEdits
• bypassPermissions (requires allowDangerouslySkipPermissions: true)
• plan
• delegate
• dontAsk

You can combine:

• explicit permissions allow/deny rules
• dynamic canUseTool callback
• settings-file loading via settingSources: ["user", "project", "local"]

Compatibility Harness

A strict side-by-side harness compares Fourmis vs @anthropic-ai/claude-agent-sdk.

Run:

bun run test:compat

Useful env vars:

• COMPAT_REPEATS=3
• COMPAT_SCENARIOS=01-simple-text,02-read-package
• COMPAT_OUTPUT_DIR=/absolute/path

Artifacts per run:

• tests/compat/output/<timestamp>/summary.json
• tests/compat/output/<timestamp>/report.md
• tests/compat/output/<timestamp>/traces/*.json

Current baseline (2026-02-17): 11/12 scenarios passing, with a known hook-deny mismatch in 08-hooks-deny-bash on the Anthropic side.

Message Model

query() yields AgentMessage envelopes, primarily:

• system (init, status, hook/task events)
• assistant (text and tool_use blocks)
• user (tool results)
• stream_event (partial deltas)
• tool_progress, tool_use_summary
• result (success or error subtype)

Install and Test

bun add fourmis-agents-sdk
bun test
bun run test:compat