Skip to main content

Built-in Tools

Built-in tools let a Custodian Agent or team agent act beyond its uploaded documents — searching the web, reading a page, or extracting text from a document by URL.

Available tools​

ToolPurpose
web_searchSearch the web for current information about a topic.
scrape_urlFetch and read the full content of a specific page URL.
parse_documentExtract text from a document at a URL (PDF, DOCX, and similar).
note

External connections (Gmail — read / send / reply) are coming soon.

Enable tools​

On a Custodian:

import { Custodian } from "@custodianlabs/sdk";

const app = await new Custodian({
  model: "gpt-4o",
  systemPrompt: "Answer using current web results when they help. Cite your sources.",
  tools: ["web_search", "scrape_url"],
}).deploy();

const reply = await app.chat("What changed in the latest OpenAI API release?");
console.log(reply?.response);

With the builder:

const app = await new CustodianBuilder()
  .withModel("gpt-4o")
  .withPrompt("You research topics and summarize them.")
  .withTools(["web_search"])
  .deploy();

On a single agent in a team:

import { Agent, AgentTeam } from "@custodianlabs/sdk";

const team = new AgentTeam({
  agents: [
    new Agent({
      name: "research",
      model: "gpt-4o",
      systemPrompt: "Research the topic and produce notes.",
      tools: ["web_search", "scrape_url"],
      outputKey: "research_notes",
    }),
    new Agent({
      name: "writer",
      model: "gpt-4o",
      systemPrompt: "Write a brief from the research notes.",
    }),
  ],
  routingMode: "workflow",
  workflowOrder: ["research", "writer"],
});

const app = await team.deploy();
const reply = await app.chat("Give me a brief on RAG evaluation methods.");
console.log(reply?.response);

Tools vs. data sources​

Use a data source when...Use a tool when...
The knowledge is stable and you have the filesThe answer depends on current or external information
You want retrieval grounded in specific documentsYou want the agent to look something up on demand
The content should be indexed onceThe source changes or is not known ahead of time

You can combine both on the same agent.

Cost and latency​

Each tool call is an extra round trip and may add latency and usage. Give the agent a prompt that tells it when to use a tool rather than always reaching for one.

Next steps​