> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://cognitio-agent.mintlify.site/installation.md) for supported operating systems and other package managers.

## 1. Create a project

```sh theme={null}
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:

```dotenv theme={null}
OPENAI_API_KEY=replace-with-your-provider-key
```

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

```gitignore theme={null}
.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](https://cognitio-agent.mintlify.site/concepts/models-and-prompts.md).

## 3. Write the agent

Create `agent.mjs`:

```js title="agent.mjs" theme={null}
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

```sh theme={null}
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](https://cognitio-agent.mintlify.site/troubleshooting.md#the-model-rejects-my-api-key), [runtime installation](https://cognitio-agent.mintlify.site/troubleshooting.md#the-runtime-cannot-be-found), or [a process that stays alive](https://cognitio-agent.mintlify.site/troubleshooting.md#the-script-does-not-exit).

## 5. Give it a useful next task

| Next step | What changes |
| - | - |
| [Read a project](https://cognitio-agent.mintlify.site/concepts/built-in-tools.md) | Replace the text-only denylist with selected built-in tools and a working directory. |
| [Add a custom tool](https://cognitio-agent.mintlify.site/cookbook/custom-tool.md) | Let the model call your own calculator function. |
| [Keep a conversation](https://cognitio-agent.mintlify.site/cookbook/session-memory.md) | Use one session for multiple messages. |
| [Stream responses](https://cognitio-agent.mintlify.site/concepts/streaming.md) | Display text or tool progress while the agent is working. |
| [Extract structured data](https://cognitio-agent.mintlify.site/cookbook/structured-extraction.md) | 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](https://cognitio-agent.mintlify.site/installation.md#typescript-projects).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.