Tools

Use tools when an agent needs to read application data, call an internal service, or perform an action. The Agent SDK validates tool boundaries and runs tool code inside your application.

Define a local tool

defineTool() accepts a description, optional JSON parameters, runtime validators, a timeout, and an execute() function.

import { defineTool } from "@phaseo/agent-sdk";

const fetchTicket = defineTool({
  id: "fetch-ticket",
  description: "Load one internal support ticket.",
  parameters: {
    type: "object",
    properties: {
      ticketId: { type: "string" },
    },
    required: ["ticketId"],
    additionalProperties: false,
  },
  timeoutMs: 3_000,
  async execute(input: { ticketId: string }, context) {
    const response = await fetch(
      `https://internal.example/tickets/${input.ticketId}`,
      { signal: context.signal },
    );

    return response.json();
  },
});

If the timeout expires, the runtime aborts context.signal, marks the run as failed, and rethrows the timeout error. Schemas can be functions or objects exposing parse() or safeParse(). Invalid model arguments and invalid tool results fail before they cross the tool boundary.

Run work in your application

Set execute: false when your application, rather than the SDK process, performs the work. Continue the paused run with the result in toolOutputs. For an interactive tool, return null from onToolCalled. After continuation, onResponseReceived can validate or transform the supplied response.

Publish progress

An async generator can yield preliminary results before returning one final result:

const indexRepository = defineTool({
  id: "index-repository",
  async *execute(input: { path: string }) {
    yield { phase: "scan" };
    yield { phase: "embed" };
    return { indexed: 248 };
  },
});

Progress is available through tool.preliminary_result events and the step’s preliminaryResults.

Run independent tools concurrently

If one model turn can safely call several independent tools, configure a concurrency limit:

const agent = createAgent({
  id: "research-agent",
  toolExecution: {
    toolConcurrency: 3,
  },
  tools: [fetchDocs, fetchStatus, fetchIncidents],
});

The runtime preserves tool-result message order even when local execution overlaps.

Start Here

Build

Observe

Reference

Define a local tool

Run work in your application

Publish progress

Run independent tools concurrently

​Define a local tool

​Run work in your application

​Publish progress

​Run independent tools concurrently

​Related guides

Define a local tool

Run work in your application

Publish progress

Run independent tools concurrently

Related guides