bio-agent

Build a bioanywhere-ready A2A agent in 60 seconds. Thin convention wrapper around @a2a-js/sdk that auto-wires:

• /.well-known/agent-card.json (built from your constructor args + skills)
• /health (with an override hook)
• /a2a JSON-RPC endpoint (delegates to the official SDK)

The fastest way to start is npx create-bio-agent my-agent — see the create-bio-agent package.

Install

npm install bio-agent @a2a-js/sdk

Quickstart

import { BioAgent } from "bio-agent";

const agent = new BioAgent({
  name: "Reverse Bot",
  description: "Reverses any text you send it.",
  version: "1.0.0",
  tags: ["text", "demo"],
}).addSkill({
  id: "reverse",
  name: "Reverse text",
  description: "Returns the input reversed.",
  examples: ["hello → olleh"],
  handler: (input) => input.split("").reverse().join(""),
});

const { url } = await agent.start({ port: 3000 });
console.log(`Agent live at ${url}`);
// Now paste the URL into https://bioanywhere.com/integrate

API

new BioAgent(options)

| option | default | notes | | ------------------- | ------------------------------------ | ------------------------------------------------ | | name | (required) | Shown in the marketplace | | description | (required) | Shown in the marketplace | | version | (required) | Semver | | tags | [] | Default tags applied to skills with no own tags | | contact | none | { organization, url } on the agent card | | iconUrl | none | | | documentationUrl | none | | | url | inferred | Public URL — uses PUBLIC_BASE_URL / REPLIT_DEV_DOMAIN / localhost | | a2aPath | /a2a | | | agentCardPath | /.well-known/agent-card.json | | | healthPath | /health | | | protocolVersion | 0.3.0 | |

agent.addSkill({...})

A skill is { id, name, description, tags?, examples?, inputModes?, outputModes?, handler }.

The handler receives (input, ctx) where input is the concatenated text of the user message and ctx contains the raw A2A message, the taskId, contextId, the matched skillId, and an AbortSignal that fires when the caller cancels.

Returns: a string, an A2A Part[], or { parts: Part[] }.

If your handler throws, the agent returns an A2A failed task with the error message; in dev mode the offending payload is also logged to stderr.

agent.health(fn)

Override the default /health response:

agent.health(async () => ({
  ok: dbConnection.isHealthy(),
  uptimeSeconds: process.uptime(),
}));

agent.start({ port?, host? })

Boots an Express server. Returns { url, port, agentCard, close() }.

agent.attach(app, port?)

For embedding bio-agent into an existing Express app.

Deploy on Replit

create-bio-agent writes a .replit config that runs your agent on Replit in one click. Set PUBLIC_BASE_URL (or rely on REPLIT_DEV_DOMAIN) so agent.url matches the URL the marketplace will hit.