Run your first agent

Create a project, connect a model, and print your first response.

You will build a small Node.js program that asks an agent a question and prints its answer. You need Node.js 22 or newer, npm, and an OpenAI API key with access to the model used below. See installation for supported operating systems and other package managers.

​

1. Create a project

mkdir my-cognitio-agent
cd my-cognitio-agent
npm init -y
npm install cognitio-agent-sdk@2.0.1

The package includes the matching native runtime through npm optional dependencies. Keep optional dependencies enabled; no separate runtime installation is needed.

​

2. Add your API key

Create a file named .env in this directory:

OPENAI_API_KEY=replace-with-your-provider-key

Create .gitignore so your key and installed packages stay out of source control:

.env
node_modules/

The run command below uses Node’s --env-file option to load .env. Cognitio can also use provider variables already set in your shell. To use another provider, change the key and model together; see models and prompts.

​

3. Write the agent

Create agent.mjs:

agent.mjs

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

if (!process.env.OPENAI_API_KEY) {
  throw new Error("Set OPENAI_API_KEY in .env before running this example.")
}

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  instructions: "Explain concepts in two short sentences.",
  disallowedTools: ["*"],
  maxTurns: 3,
})

try {
  const result = await agent.run("How does an agent use a tool?")
  if (result.isError) throw new Error(`Agent stopped: ${result.subtype}`)
  console.log(result.text)
} finally {
  await agent.close().finally(() => shutdown())
}

• model selects the provider and model as provider/model.
• instructions describes the behavior you want to reuse across tasks.
• disallowedTools: ["*"] makes this a text-only first run.
• maxTurns limits model turns within one task.
• run() returns the final answer and run metadata.
• shutdown() releases the shared local runtime when this script is finished.

​

4. Run it

node --env-file=.env agent.mjs

You should see a short explanation of how a model selects a tool and uses its result. The exact wording varies. When the response is complete, the script exits.

No extra isolation setup is required: the SDK starts with its own runtime configuration and temporary state. It does not automatically load your personal agent configuration. This is configuration isolation, not an operating-system sandbox for tools.

If the program fails, start with missing credentials, runtime installation, or a process that stays alive.

​

5. Give it a useful next task

Next step	What changes
Read a project	Replace the text-only denylist with selected built-in tools and a working directory.
Add a custom tool	Let the model call your own calculator function.
Keep a conversation	Use one session for multiple messages.
Stream responses	Display text or tool progress while the agent is working.
Extract structured data	Receive and validate a typed object.

The rest of the guides use TypeScript where types help explain an API. You can run those examples with the TypeScript setup.