⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
@repo/agent-tools
Custom tools for AI agents: external services (Jina, Firecrawl, Telegram) an agent can call at runtime. Each service is an integration that owns a credential and exposes one or more tools.
Model
- Integration: an external service. Holds a
credentialSchema(the fields a human fills once per credential, such as an API key) and a list of tools. - Tool: one callable action. Declares an
inputSchema(what the model passes at call time) and anexecutethat runs it with the decrypted credential.
A team can store several credentials per integration, and a configured tool binds one tool to one credential. That way two Jina keys can back two copies of the same tool.
Add a tool to an existing integration
You only touch that integration's folder.
Create
src/tools/<integration>/<action>.ts:import { z } from "zod"; import type { CustomToolEntry } from "../../types"; import { jsonOrThrow } from "../../http"; export const telegramFoo: CustomToolEntry = { key: "telegram_foo", // unique across ALL integrations label: "Telegram Foo", description: "What the tool does. Passed to the model verbatim.", inputSchema: z.object({ text: z.string().min(1).describe("Field docs help the model."), }), execute: async (credential, input) => { const res = await fetch("https://api.telegram.org/...", { ... }); return await jsonOrThrow(res, "Telegram foo"); }, };Add it to the
toolsarray insrc/tools/<integration>/index.ts.
That's it. The registry indexes it, the API catalog exposes it, and the runtime resolves it.
Add a new integration
Create
src/tools/<name>/:one file per tool (
CustomToolEntry, as above);index.tsexporting theIntegration:import type { Integration } from '../../types'; import { myToolA } from './a'; export const myService: Integration = { key: 'my_service', label: 'My Service', credentialSchema: [{ key: 'apiKey', label: 'API key', type: 'secret', required: true }], tools: [myToolA], };
Register it in
src/registry.ts. This is the one manual step: import the integration and add it to theINTEGRATIONSarray.
Everything downstream reads from that array: the tool index, the
integrationDescriptors() catalog for the UI, and coerceConfig/redactConfig. No
other file needs editing.
Integrations from outside this package
A build that extends the api adds integrations of its own at startup with
setExtraIntegrations([...]). They join the core's in the tool index and the catalog.
Each call replaces the previous ones, and a call without an argument removes them. A
key that is already taken throws. A configured tool whose integration is removed stays
stored, and the runtime skips it.
An integration without a credential
An integration whose tools need no account with an external service (PDF downloads
the file and parses it in the api process) declares credentialSchema: []. Its tools are configured without a
credential, its execute receives {}, and the API refuses to store a credential for
it.
Rules
- A tool
keyis unique across all integrations. The tool index is a flat map by key; a duplicate throws whenregistry.tsloads or whensetExtraIntegrationsadds it. - Mark secrets
type: "secret"incredentialSchema. Non-secret fields are stored in plaintext and shown unredacted in the list UI. - Throw a clear
Erroron failure. The runtime catches it and returns{ error: message }to the model instead of aborting the run, so that message is the model's only signal. UsejsonOrThrowfromhttp.tsfor fetch calls. executereceives the decrypted credential, keyed bycredentialSchemafield key. Read config values off it; the model never sees the secret.
Config field types
string, secret, url, number, boolean. coerceConfig validates and coerces
submitted values against the schema; a missing required field returns a 400.