Cortex · guide

An agent with a tool

A tool is a function with a schema for what it takes. An agent is given the tool, asked a question, and answers from what the tool returned.

Install it

pnpm add @niscorp/cortex @niscorp/signal zod openai

Step 1 of 4

The model

createSignal makes the client that calls the model. Cortex is handed this client, here for Groq, and Signal reads the key from GROQ_API_KEY.

The model

import { z } from 'zod';
import { createSignal } from '@niscorp/signal';
import { defineAgent, defineTool } from '@niscorp/cortex';

const llm = createSignal('groq');

Step 2 of 4

A tool

A tool has an id, the name the model calls it by, a sentence saying what it does, a schema for its input, and the function.

The model is sent the name, the sentence and the schema. When it calls the tool, Cortex checks the arguments against the schema before the function runs.

A tool

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: night === '2026-10-24' ? 113 : 120 }),
});

Step 3 of 4

The agent

This agent is its instructions and its tools. With no output schema it is a chat agent: its answer is text.

The agent

const boxOffice = defineAgent({
  id: 'box-office',
  instructions: 'Look the night up with the seatsLeft tool, then answer in one sentence.',
  tools: [seatsLeft],
});

Step 4 of 4

Run the agent

run starts the loop: the model is asked, it calls the tool, Cortex runs the function and hands the result back, and the model answers.

A run does not throw. result.ok says whether it ended with an answer, and when it did not, result.error says why.

Run the agent

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

if (result.ok) console.log(result.output.response);
else console.log(result.error.code, result.error.message);
console.log('steps:', result.meta.steps);

Then

Run it.

This file asks a model, so it is not run on this site. When the model calls the tool once and then answers, it prints the model’s sentence, which names the 113 seats the tool returned, and steps: 2: one step for the call, one for the answer.

Run it

GROQ_API_KEY=your-key npx tsx agent.mts