AgentX (@x12i/agentx)

AgentX is an npm library that runs a prompt-driven agent loop against tools discovered from FuncX, NxFunc, Tavily, and other MCP servers over streamable HTTP.

It composes @x12i/funcx ≥ 3.7 runToolLoop (OpenRouter-capable chat client) with @modelcontextprotocol/sdk MCP clients (same SDK FuncX uses on the server side).

FuncX 3.7+ MCP alignment

• FuncX as MCP server: From v3.7, the catalog is exposed as an MCP server via @x12i/funcx/mcp (createFuncXMcpHttpServer, funcx-mcp CLI, streamable HTTP). Registered tool names follow the funcx.<functionId> pattern.
• AgentX as MCP client: FUNCX_MCP must be the streamable-HTTP MCP URL of that FuncX deployment — the same endpoint a generic MCP client would use. AgentX does not import @x12i/funcx/mcp (that entrypoint is the heavy server implementation); it only calls your hosted MCP over HTTP using the SDK client, which stays aligned with FuncX’s protocol choices.
• NxFunc / Tavily: unchanged — NXFUNC_MCP and Tavily env vars point at their respective MCP servers; AgentX discovers tools from all configured servers the same way.

Install

npm install @x12i/agentx

Configure

AgentX consumes tools from your MCP deployments — it does not invent FuncX/NxFunc/Tavily endpoints. If those MCP URLs are missing, createAgentX() throws AgentXMcpConfigurationError with an explicit checklist (no silent “LLM-only” fallback).

Copy .env.example and set at least:

• OPENROUTER_API_KEY — FuncX OpenRouter backend for the model loop
• FUNCX_MCP, NXFUNC_MCP — required streamable-HTTP MCP URLs for the live FuncX and NxFunc catalogs your operators host
• TAVILY_MCP or TAVILY_API_KEY — required while search is enabled (default); URL can be derived from the API key

Optional: AGENTX_MODEL, AGENTX_MODE, AGENTX_MAX_TOOLS, AGENTX_MAX_STEPS, AGENTX_MAX_TOOL_CALLS, AGENTX_REQUIRE_APPROVAL_FOR_RISKY_TOOLS.

Escape hatches (tests / special runs only): mcp.allowMissingCatalogMcp, mcp.allowMissingSearchMcp, or search: { enabled: false } when you intentionally run without Tavily.

You can also pass explicit mcp.servers entries instead of env vars (same sources: funcx, nxfunc, tavily).

Usage

import "dotenv/config";
import { createAgentX } from "@x12i/agentx";

// By default, env FUNCX_MCP, NXFUNC_MCP, Tavily (TAVILY_MCP or TAVILY_API_KEY), and OPENROUTER_API_KEY must be set (or pass equivalent mcp.servers).
const agentx = await createAgentX();

const out = await agentx.run({
  prompt: "List available nxfunc capabilities related to risk.",
});

console.log(out.ok, out.response);
console.log(out.toolCalls);

Repository

Source and issues: github.com/x12i/agentx

Docs

Product specification: docs/specs.md (in-repo). Dynamic agent authoring (Catalox-backed) is planned as a later phase; SDK methods for stored agents are currently stubs.

License

MIT