convez.ai
AgenteIntegração & APIsIntermediário
jcanizalez

Fourmis Agents SDK

jcanizalez/fourmis-agent-sdk

SDK de agentes IA multi-provider com tools e MCP embutidos

Ver no GitHub
InicialPluginScore · de 0 a 100

SDK multi-provider para agentes de IA com acesso direto à API e execução de ferramentas no processo. Suporta Anthropic, OpenAI e Gemini com interface unificada, hooks de ciclo de vida, execução de tools in-process e integração com MCP servers.

Instalação

$npx convez-ai jcanizalez/fourmis-agent-sdk

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 9 meses
Versão
v0.4.1
Issues abertas
1
Contribuidores
1

Casos de uso

  • Construir agentes que leem e modificam arquivos do sistema
  • Executar comandos bash e scripts de automação via agentes
  • Integrar múltiplos provedores de IA (Anthropic, OpenAI, Gemini) em um único fluxo
  • Criar pipelines de análise com busca web e fetch de URLs

Veredito

SDK robusto para construção de agentes IA com suporte multi-provider e controle fino do loop de agente. Requer Bun v1.0+, o que limita adoção em ambientes Node puros, mas oferece abstração bem pensada sobre providers e tools.

README

A tradução para o português deste README ainda está na fila.

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:

ProviderAuth
anthropicANTHROPIC_API_KEY or Claude OAuth token
openaiOPENAI_API_KEY or OpenAI/Codex OAuth
geminiGEMINI_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:

ToolPurpose
BashShell command execution
ReadRead files with line numbers
WriteWrite/overwrite files
EditExact string replacement
GlobFile pattern matching
GrepRegex content search
NotebookEditEdit Jupyter notebook cells
WebFetchFetch URL content
WebSearchLightweight web search
TodoWritePersist todo state
ConfigRead/write .claude/settings*.json
AskUserQuestionAsk user (returns runtime-unavailable error in this host mode)
ExitPlanModeRequest 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
Ver o original no GitHub

Bom para

Relacionados