BUILD

Agents & tools

An agent turns a goal into finished work. You give it typed tools, safe, explicit capabilities, and it plans, acts, and verifies, streaming every decision as it goes.

Defining a tool

A tool has a name, a description the model reads, a typed input schema, and a handler you control.

import { Taskclan, tool } from "@taskclan/sdk";
import { z } from "zod";

const getWeather = tool({
  name: "get_weather",
  description: "Get the current weather for a city",
  input: z.object({ city: z.string() }),
  async run({ city }) {
    const res = await fetch(`https://api.example.com/weather?city=${city}`);
    return res.json();
  },
});

Running an agent with tools

const taskclan = new Taskclan({ apiKey: process.env.TASKCLAN_API_KEY });

const result = await taskclan.run({
  profile: "t1-flow",
  goal: "Should I bring an umbrella to Toronto tomorrow?",
  tools: [getWeather],
  verify: true,
});

console.log(result.output);

Streaming plans & tool calls

Observe the agent’s plan, each tool call, and the result as events, ideal for transparent UIs and debugging.

const stream = await taskclan.run.stream({
  profile: "t1-flow",
  goal: "Reconcile these two invoices",
  tools: [lookupInvoice, postAdjustment],
});

for await (const event of stream) {
  switch (event.type) {
    case "plan":       console.log("plan:", event.steps); break;
    case "tool_call":  console.log("calling", event.name, event.input); break;
    case "tool_result":console.log("result", event.output); break;
    case "text":       process.stdout.write(event.delta); break;
  }
}

Verification

With verify: true, the Engine’s evaluation layer checks output quality, policy and rights before returning. Add your own checks with evaluation hooks to test business outcomes, not just text.

Good tool design

• Give each tool a single, clear purpose and a descriptive name.
• Validate inputs with a schema; return structured, predictable outputs.
• Make tools idempotent where possible, and never expose more scope than needed.