Tools

Define a tool with an input schema and an execute function. Here, the agent can look up a product by its code:

import { createFxAgent } from 'libfx'

const products = new Map([['FX-1', { name: 'Desk lamp', stock: 12 }]])
const agent = await createFxAgent({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  instructions: 'Use lookup to answer questions about product availability.',
  tools: [{
    name: 'lookup',
    description: 'Look up a product by code.',
    inputSchema: {
      type: 'object',
      properties: { code: { type: 'string' } },
      required: ['code'],
      additionalProperties: false,
    },
    async execute(input) {
      if (typeof input.code !== 'string') throw new Error('A product code is required')
      return products.get(input.code) ?? { error: 'Product not found' }
    },
  }],
})
try {
  const turn = agent.prompt('Is FX-1 in stock?')
  for await (const event of turn) {
    if (event.type === 'text_delta') process.stdout.write(event.delta)
  }
  await turn.result
} finally {
  await agent.close()
}

Your application validates inputs and authorizes operations inside execute(). CLI permission prompts do not approve SDK tools. Long-running tools should honor the provided cancellation signal; cancellation stops waiting for a result but cannot undo an operation your code already performed.

Use instructions for the agent's system message. Supply the tools and project context it needs when creating it. See HostTool for the callback contract.

Connect existing tools

Use the MCP adapter to give the agent tools from an MCP server.