Tooling

Tools are the external capabilities available to BeeSystem agents. Every tool has a typed input contract, typed output contract, and defined error behavior.

Built-in tools

Tool	Description
`web_search`	Search the web via configured search API
`document_reader`	Read PDF, TXT, MD, HTML documents
`structured_writer`	Write structured output (JSON, YAML, Markdown)
`api_connector`	Make HTTP API calls with configured credentials
`database_query`	Run typed queries against configured databases
`file_system`	Read and write files in the agent workspace
`shell_exec`	Execute shell commands (requires explicit capability)

Custom tools with the SDK

tools/my-api.tstypescript

import { defineTool } from "@beesystem/sdk";

export const myApiTool = defineTool({
  name: "my_api",
  description: "Calls My API with the given query",
  input: {
    query: { type: "string", required: true },
    limit: { type: "number", default: 10 },
  },
  output: {
    results: { type: "array" },
    total: { type: "number" },
  },
  async execute({ query, limit }) {
    const response = await fetch(`https://api.example.com/search?q=${query}&limit=${limit}`);
    if (!response.ok) {
      throw new ToolError("API_UNAVAILABLE", `Status ${response.status}`);
    }
    return response.json();
  },
});

All tool implementations must call real APIs. Never simulate or mock tool responses — if the dependency is unavailable, throw a structured ToolError and stop.

Tool configuration in agent spec

agent.yamlyaml

tools:
  - name: my_api
    type: custom
    module: ./tools/my-api.ts
    config:
      timeout: 10s
      retry: 2