Commands

Name: Surf
Author: Surf

Define typed commands for AI agents

Commands#

Commands are the core building block of a Surf API. Each command has a name, description, optional parameters, and a handler function.

typescript

const surf = await createSurf({
  name: 'My Store',
  commands: {
    search: {
      description: 'Search products by keyword',
      params: {
        query: { type: 'string', required: true, description: 'Search term' },
        limit: { type: 'number', default: 10 },
      },
      returns: { type: 'object' },
      tags: ['catalog', 'public'],
      hints: {
        idempotent: true,
        sideEffects: false,
        estimatedMs: 50,
      },
      run: async ({ query, limit }) => {
        return db.products.search(query, { limit })
      },
    },
  },
})

💡 Tip: The hints object helps AI agents make smart decisions — for example, knowing a command is idempotent means it's safe to retry on failure.

Edit this page on GitHub

PreviouscreateSurf Next defineCommand