@beforequery/agents - BeforeQuery

Works in Node.js v18+, browsers, and React Native.

Install

npm install @beforequery/agents

Client setup

Browser (public key)
Node.js (client credentials)

import { BeforeQueryAgents } from "@beforequery/agents";

const client = new BeforeQueryAgents({ clientKey: "bq_pk_your_public_key" });

import { BeforeQueryAgents } from "@beforequery/agents";

const client = new BeforeQueryAgents({
  clientId: "bq_ci_your_client_id",
  clientSecret: "bq_cs_your_client_secret",
});

Options: clientKey (browser/RN) or clientId + clientSecret (server), plus optional baseUrl (default https://api.agents.beforequery.com).

Run an agent

const result = await client.runAgent("agent_xxx", "Explain the rate-limiting strategy");

console.log(result.output);   // final answer text
console.log(result.status);   // "completed" | "pending_approval"
console.log(result.steps);    // node-by-node execution trace

if (result.status === "pending_approval") {
  console.log("Approval required:", result.approval_request_id);
}

MCP tools

Typed wrappers over the project MCP server; the JSON-RPC initialize handshake happens lazily:

const results = await client.searchDocs("proj_xxx", "pgvector cosine similarity", { limit: 5 });
const answer  = await client.askQuestion("proj_xxx", "What is the recommended chunk size?");
const sources = await client.listSources("proj_xxx");

A2A protocol

const card = await client.getAgentCard("proj_xxx");       // public, no auth
const result = await client.sendMessage("proj_xxx", "What can you help me with?");

defineAgent — graph as code

Define and validate agent graphs in TypeScript; the output matches the backend JSON format:

import { defineAgent } from "@beforequery/agents";

const graph = defineAgent({
  nodes: [
    { id: "coordinator", type: "coordinator", name: "Orchestrator",
      instructions: "Route the user's request to the right specialist agent.",
      model: "gpt-4o" },
    { id: "search", type: "specialist", name: "Search Agent", tools: ["search_docs"] },
    { id: "qa", type: "specialist", name: "Q&A Agent", tools: ["ask_question"] },
  ],
  edges: [
    { from: "coordinator", to: "search" },
    { from: "coordinator", to: "qa" },
  ],
});

Validation rules: at least one node; exactly one coordinator; unique node ids; edges must reference existing nodes; self-loops rejected. Violations throw AgentGraphError.

Error handling

import { BeforeQueryAgentsError, McpError, A2AError } from "@beforequery/agents";
// BeforeQueryAgentsError → agent API (err.status), McpError → JSON-RPC (err.code), A2AError → A2A (err.code)

Self-hosted agent runtime

The package ships an HTTP runtime server so you can execute agent graphs on your own infrastructure (credentials still authenticate against the BeforeQuery API for retrieval and LLM calls).

docker build -f docker/Dockerfile.agent-runtime -t beforequery-agent-runtime .

docker run -p 8380:8380 \
  -e BEFOREQUERY_CLIENT_ID=bq_ci_... \
  -e BEFOREQUERY_CLIENT_SECRET=bq_cs_... \
  -v /path/to/your/agents:/agents:ro \
  beforequery-agent-runtime

Agent definitions are .json files in the mounted directory — either a named manifest with remoteAgentId (proxies to a cloud agent) or a bare graph (filename stem becomes the agent ID, validated by defineAgent at startup).

Env var	Default	Description
`BEFOREQUERY_CLIENT_KEY`	—	Public key credential set
`BEFOREQUERY_CLIENT_ID` / `BEFOREQUERY_CLIENT_SECRET`	—	Server credential set
`BEFOREQUERY_API_URL`	`https://api.agents.beforequery.com`	Override API base URL
`AGENTS_DIR`	`/agents`	Directory of agent JSON files
`PORT`	`8380`	HTTP port

Runtime endpoints: GET /healthz, GET /agents, POST /run/:agentId with body { input, context? }.

Local testing

const client = new BeforeQueryAgents({
  clientId: "bq_ci_…",
  clientSecret: "bq_cs_…",
  baseUrl: "http://localhost:8280",
});
// Self-hosted runtime: BEFOREQUERY_API_URL=http://localhost:8280

​Install

​Client setup

​Run an agent

​MCP tools

​A2A protocol

​defineAgent — graph as code

​Error handling

​Self-hosted agent runtime

​Local testing