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.

The two natures of an agent

“Agent” on Taskclan means two related but distinct things. The /agents catalog is split down the middle for exactly this reason:

Extensions you install — general-purpose Skills (inline VS Code slash commands like /roast, /plan, /refactor) and project Templates. Developer-facing. Install once, use forever.
Product agents that ship — Agents, Workflows and Prompts that already run inside our products (Nani Voice, Nani Coach, GameNova intent classification, Forge3D → GameNova cross-sell). They’re proof the platform works, and they’re grouped by product on the catalog page.

Same runtime. Extensions and product agents are built on identical primitives: the client, tools, streaming events, and the evaluation layer described below. The examples on this page apply to both; the difference is where they run and who invokes them.

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;
  }
}

Human in the loop. For consequential or irreversible actions, require confirmation before a tool runs. Keep people accountable, see the AI Policy.

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.