Tools

Tools are typed, validated functions that agents can call during execution.

Defining a Tool

import { Tool } from 'gravity-sdk';
import { z } from 'zod';

const searchTool = new Tool({
  name: 'searchWeb',
  description: 'Search the web for a query and return results',
  schema: z.object({
    query: z.string().describe('The search query'),
    maxResults: z.number().optional().describe('Max results to return'),
  }),
  execute: async ({ query, maxResults = 5 }) => {
    // Your implementation here
    return { results: [`Result for: ${query}`] };
  }
});

Adding Tools to an Agent

const agent = new Agent({
  name: 'ResearchBot',
  instructions: 'You are a research assistant. Use searchWeb to answer questions.',
  model: new DeepSeekProvider(),
  memory: new InMemoryProvider(),
  tools: [searchTool],
});

Tool Error Handling

If a tool throws, the error is caught and fed back to the model safely — the agent loop continues and the model can recover.

const riskyTool = new Tool({
  name: 'fetchData',
  description: 'Fetch data from an API',
  schema: z.object({ url: z.string().url() }),
  execute: async ({ url }) => {
    const res = await fetch(url);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  }
});

Handoff via Tool

A tool can return a Handoff to transfer control to another agent:

import { Handoff } from 'gravity-sdk';

const escalateTool = new Tool({
  name: 'escalateToExpert',
  description: 'Escalate to a domain expert agent',
  schema: z.object({ reason: z.string() }),
  execute: ({ reason }) => new Handoff('ExpertAgent', { reason }),
});