Cortex · API

defineAgent

defineAgent creates an agent from its configuration: id, instructions, tools and an output schema (output.schema). agent.run(input, { llm }) starts a run, and run.result resolves with the run’s result. The model’s two turns are scripted; no model is called.

Tool and agent

const seatsLeft = defineTool({
  id: 'seatsLeft',
  name: 'seatsLeft',
  description: 'How many seats are left on a night',
  input: z.object({ night: z.string().describe('The night, as YYYY-MM-DD') }),
  execute: ({ night }) => ({ night, left: seatsLeftOn(night) }),
});

const boxOffice = defineAgent({
  id: 'box-office',
  instructions: 'Look the night up with the seatsLeft tool, then give the answer.',
  tools: [seatsLeft],
  output: { schema: z.object({ left: z.number() }) },
});

const result = await boxOffice.run('How many seats are left on 2026-10-24?', { llm }).result;

Scripted model turns

1  calls seatsLeft {"night":"2026-10-24"}
2  writes {"data":{"left":113}}

Result

{
  ok: true,
  output: { data: { left: 113 } },
  meta: { strategy: 'native', steps: 2, outputRetries: 0 },
}

Output matches the expected value

Runs in this page on the installed package. The input and the expected output are defined by the example.