Tools

import { defineTool } from '@standardagents/spec';
import { z } from 'zod';

export default defineTool({
  description: 'Search the customer database for matching records',
  args: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10).describe('Maximum results'),
  }),
  execute: async (state, args) => {
    const results = await searchDatabase(args.query, args.limit);

    return {
      status: 'success',
      result: JSON.stringify(results),
    };
  },
});

// Function tool: agents/tools/lookup_customer.ts
export default defineTool({
  description: 'Look up customer by ID',
  args: z.object({ customerId: z.string() }),
  execute: async (state, args) => {
    const customer = await db.getCustomer(args.customerId);
    return { status: 'success', result: JSON.stringify(customer) };
  },
});

// Prompt tool: agents/prompts/summarizer.ts
export default definePrompt({
  name: 'summarizer',
  toolDescription: 'Summarize text into key points',
  prompt: 'You are an expert summarizer...',
  model: 'gpt-6.1-sol',
  requiredSchema: z.object({
    text: z.string().describe('Text to summarize'),
  }),
});

// Agent tool: agents/agents/billing_specialist.ts
export default defineAgent({
  name: 'billing_specialist',
  exposeAsTool: true,
  toolDescription: 'Hand off billing issues to specialist',
  sideA: { prompt: 'billing_expert' },
  sideB: { human: true },
});

// Use all three in a prompt
export default definePrompt({
  name: 'support_router',
  tools: [
    'lookup_customer',      // Function tool
    'summarizer',           // Prompt tool
    'billing_specialist',   // Agent tool
  ],
  // ...
});

defineTool({
  description: 'My tool',
  args: z.object({ input: z.string() }),
  execute: async (state, args) => {
    // Access execution context
    console.log('Thread ID:', state.threadId);
    console.log('Step:', state.execution?.stepCount);
    console.log('Agent:', state.agentId);

    // Access the thread key-value store
    const result = await state.getValue(`data:${args.input}`);

    // Access environment
    const apiKey = await state.env('MY_API_KEY');

    return { status: 'success', result: 'Done' };
  },
});

const run = state.runCode(code, {
  execute: { fn: 'main', args: ['notes.txt'] },
  imports: {
    fs: {
      readFile: async (path: string) => {
        const data = await state.readFile(path);
        return data ? new TextDecoder().decode(data) : null;
      },
    },
  },
  report: (value) => console.log('sandbox report', value),
});

const result = await run;

const argsSchema = z.object({
  // Required string
  query: z.string().describe('Search query'),

  // Optional with default
  limit: z.number().optional().default(10).describe('Max results'),

  // Enum
  format: z.enum(['json', 'text', 'markdown']).describe('Output format'),

  // Nested object
  filters: z.object({
    category: z.string().optional(),
    minPrice: z.number().optional(),
  }).optional().describe('Filter options'),

  // Array
  tags: z.array(z.string()).optional().describe('Filter by tags'),
});

interface ToolResult {
  status: 'success' | 'error';
  result?: string;
  error?: string;
  error_code?: string;
  error_data?: Record<string, unknown>;
  stack?: string;
  attachments?: Array<ToolAttachment | AttachmentRef>;
}

interface ToolAttachment {
  name: string;           // Filename (e.g., "generated.png")
  mimeType: string;       // MIME type
  data: string;           // Base64-encoded file data
  width?: number;         // Image width in pixels
  height?: number;        // Image height in pixels
}

return {
  status: 'success',
  result: 'Operation completed successfully',
};

return {
  status: 'success',
  result: JSON.stringify({ id: '123', name: 'John' }),
};

return {
  status: 'error',
  error: 'Failed to find user: User not found',
};

export default defineTool({
  description: 'Search through uploaded files using vector embeddings',
  args: z.object({
    query: z.string().describe('Search query'),
  }),
  execute: async (state, args) => {
    const vectorStoreId = await state.env('VECTOR_STORE_ID');
    const results = await searchVectorStore(vectorStoreId, args.query);
    return { status: 'success', result: JSON.stringify(results) };
  },
  variables: [
    {
      name: 'VECTOR_STORE_ID',
      type: 'secret',
      required: true,
      description: 'OpenAI Vector Store ID',
    },
  ],
});

export default defineModel({
  name: 'gpt-6.1-sol-with-tools',
  provider: openai,
  model: 'gpt-6.1-sol',
  providerTools: ['web_search', 'code_interpreter'],
});

import { defineTool } from '@standardagents/spec';
import { z } from 'zod';

export default defineTool({
  description: 'Look up customer information by ID or email',
  args: z.object({
    customerId: z.string().optional().describe('Customer ID'),
    email: z.string().email().optional().describe('Customer email'),
  }),
  execute: async (state, args) => {
    const databaseUrl = await state.env('DATABASE_URL');

    let customer;
    if (args.customerId) {
      customer = await lookupCustomer(databaseUrl, { customerId: args.customerId });
    } else {
      customer = await lookupCustomer(databaseUrl, { email: args.email });
    }

    if (!customer) {
      return {
        status: 'error',
        error: 'Customer not found',
      };
    }

    return {
      status: 'success',
      result: JSON.stringify(customer),
    };
  },
});

import { defineTool } from '@standardagents/spec';
import { z } from 'zod';

export default defineTool({
  description: 'Fetch current weather for a city',
  args: z.object({
    city: z.string().describe('City name'),
    units: z.enum(['metric', 'imperial']).default('metric'),
  }),
  execute: async (state, args) => {
    const apiKey = await state.env('WEATHER_API_KEY');

    try {
      const response = await fetch(
        `https://weather.example.com/v1/current?city=${encodeURIComponent(args.city)}&units=${args.units}&key=${encodeURIComponent(apiKey ?? "")}`
      );

      if (!response.ok) {
        return {
          status: 'error',
          error: `Weather API error: ${response.status}`,
        };
      }

      const data = await response.json();

      return {
        status: 'success',
        result: `Weather in ${args.city}: ${data.temperature}°, ${data.conditions}`,
      };
    } catch (error) {
      return {
        status: 'error',
        error: `Failed to fetch weather: ${error instanceof Error ? error.message : String(error)}`,
      };
    }
  },
});

import { defineTool } from '@standardagents/spec';
import { z } from 'zod';

export default defineTool({
  description: 'Process order and queue follow-up tasks',
  args: z.object({
    orderId: z.string().describe('Order ID'),
  }),
  execute: async (state, args) => {
    const order = await validateOrder(args.orderId);

    if (!order.valid) {
      return {
        status: 'error',
        error: 'Order validation failed',
      };
    }

    // Queue additional tools to execute after this one
    state.queueTool('charge_payment', {
      orderId: args.orderId,
      amount: order.total,
    });

    state.queueTool('send_confirmation_email', {
      userId: order.userId,
      orderId: args.orderId,
    });

    return {
      status: 'success',
      result: `Order ${args.orderId} queued for processing`,
    };
  },
});

export default defineTool({
  description: 'Generate an image based on a text prompt',
  args: z.object({
    prompt: z.string().describe('Text description of the image'),
  }),
  execute: async (state, args) => {
    const image = await generateImage(args.prompt);

    return {
      status: 'success',
      result: `Generated image for: "${args.prompt}"`,
      attachments: [{
        name: `generated-${Date.now()}.png`,
        mimeType: 'image/png',
        data: image.base64,
        width: 1024,
        height: 1024,
      }],
    };
  },
});