Build a small chat CLI

Run a complete text-only agent with Node.js and the published npm package.

Ask one question and print the answer. Each run starts a fresh conversation. The complete code is below. You can also browse the project on GitHub or open its JavaScript source.

​

1. Create the project

Use Node.js 22 or newer, npm, and an OpenAI API key with access to gpt-4.1-mini. Model requests use your provider account and can incur charges.

mkdir cognitio-chat
cd cognitio-chat
npm init -y
npm install --save-exact cognitio-agent-sdk@2.0.1

Keep npm optional dependencies enabled; they include the runtime for your platform. You do not need a separately installed runtime.

​

2. Configure the environment

Create a file named .env in this directory:

COGNITIO_MODEL=openai/gpt-4.1-mini
OPENAI_API_KEY=replace_with_your_key

Replace the placeholder with your key. Add .env and node_modules/ to .gitignore. Existing shell environment values take precedence over this file. To use Anthropic instead, set COGNITIO_MODEL=anthropic/claude-sonnet-4-5 and ANTHROPIC_API_KEY to your Anthropic key; the code forwards either provider’s credential.

​

3. Create index.mjs

import { Agent } from "cognitio-agent-sdk"

const model = process.env.COGNITIO_MODEL?.trim() || "openai/gpt-4.1-mini"
const credential = { openai: "OPENAI_API_KEY", anthropic: "ANTHROPIC_API_KEY" }[model.split("/")[0]]
if (!model.includes("/")) throw new Error("Set COGNITIO_MODEL to a provider/model identifier.")
if (credential && (!process.env[credential]?.trim() || process.env[credential] === "replace_with_your_key")) {
  throw new Error(`Set ${credential} in .env or your shell before running this example.`)
}
const providerEnv = Object.fromEntries(
  ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]
    .filter((name) => process.env[name]?.trim())
    .map((name) => [name, process.env[name]]),
)

const agent = new Agent({
  model,
  instructions: "Explain things clearly and briefly. Do not call tools.",
  settingSources: [],
  includeEnvironment: false,
  disallowedTools: ["*"],
  maxTurns: 1,
  maxBudgetUsd: 0.03,
  spawn: {
    isolated: true,
    port: 0,
    autoCleanup: true,
    env: { ...providerEnv, COGNITIO_DISABLE_AUTOUPDATE: "1", COGNITIO_DISABLE_LSP_DOWNLOAD: "1" },
    config: { plugin: [], lsp: false, formatter: false, agent: { title: { disable: true } } },
  },
})

try {
  const result = await agent.run("In two short sentences, explain what an agent SDK does.", {
    signal: AbortSignal.timeout(90_000),
  })
  if (result.isError || result.subtype !== "success") throw new Error(`Chat failed: ${result.subtype}`)
  if (typeof result.text !== "string" || !result.text.trim()) throw new Error("The model returned no answer.")
  console.log(result.text.trim())
} finally {
  await agent.close()
}

​

4. Run it

node --env-file=.env index.mjs

A successful run prints a short answer, for example:

An agent SDK connects a language model to your application's tools and state.
It manages the conversation and tool loop so you can focus on the task.

The wording varies by model and run. The script rejects unsuccessful results and empty answers. Change the string passed to agent.run() to ask a different question.

​

How it works

disallowedTools: ["*"] makes this a text-only agent. An empty allowedTools list would leave tools unrestricted. The example omits environment details from the prompt and does not load user or project instructions.

The explicit spawn configuration gives this Agent its own isolated runtime. agent.close() in finally stops it even when the request fails. The request has a 90-second cancellation deadline and a one-turn limit. The estimated $0.03 budget is checked using reported usage; it is not a prepaid spending cap.

For streamed output, see streaming and cancellation. To keep context between messages, use the conversation recipe.

​

Use the existing project

If you prefer the complete GitHub project, copy that directory, run npm ci, copy .env.example to .env, set your key, and run npm start. On PowerShell, use Copy-Item .env.example .env; in a Unix shell, use cp .env.example .env.