> ## 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.

# Cognitio Agent SDK

> Build agents that use tools, remember conversations, and work inside your application.

Cognitio Agent SDK gives your JavaScript or TypeScript application an agent loop: a model chooses a tool, receives its result, and continues until the task is complete. You choose the model, instructions, tools, and permissions.

It is **built on OpenCode** and includes a matching local runtime. Install one npm package; you do not need to install or launch a separate CLI.

## Start with a working agent

The [quickstart](https://cognitio-agent.mintlify.site/quickstart.md) takes you from an empty directory to a running agent using Node.js and a provider API key.

```js theme={null}
import { Agent, shutdown } from "cognitio-agent-sdk"

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

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

This example uses `OPENAI_API_KEY` from your environment and disables tools for its first text-only response. The quickstart includes installation, credentials, the run command, and expected output.

## What you can build

| Your application needs to… | Start here |
| - | - |
| Read files, search a project, or run a command | [Built-in tools](https://cognitio-agent.mintlify.site/concepts/built-in-tools.md) |
| Call your own API or business logic | [Custom tools](https://cognitio-agent.mintlify.site/concepts/tools.md) |
| Remember earlier messages | [Sessions and conversations](https://cognitio-agent.mintlify.site/concepts/sessions.md) |
| Display an answer as it arrives | [Streaming](https://cognitio-agent.mintlify.site/concepts/streaming.md) |
| Return a typed object | [Structured output](https://cognitio-agent.mintlify.site/concepts/structured-output.md) |
| Decide which actions need approval | [Permissions](https://cognitio-agent.mintlify.site/concepts/permissions.md) |
| Connect external tools and data | [MCP](https://cognitio-agent.mintlify.site/concepts/mcp.md) |
| Delegate a focused task | [Subagents](https://cognitio-agent.mintlify.site/concepts/subagents.md) |
| Track usage and handle failures | [Observability](https://cognitio-agent.mintlify.site/concepts/observability.md) and [troubleshooting](https://cognitio-agent.mintlify.site/troubleshooting.md) |

## Choose an entry point

Start with **`Agent`**. It holds reusable configuration; `agent.run()` completes one task, and `await agent.createSession()` creates a conversation. Use **`query()`** when you want one streamed task without managing an Agent object. Use **`createAgentClient()`** when your application needs direct ownership of the runtime and its sessions.

All three use the same runtime. Local execution starts with isolated configuration and state by default. There is no isolation flag to enable. See [runtime defaults](https://cognitio-agent.mintlify.site/defaults-and-isolation.md) when you need custom credentials, persistent state, or host configuration.

## Learn by running a project

The [cookbooks](https://cognitio-agent.mintlify.site/cookbook/examples.md) include complete code and commands for a chat CLI, contact extraction, a custom calculator tool, and a conversation with memory. Each recipe also links to its source on GitHub.

The **[SDK reference](https://cognitio-agent.mintlify.site/api-reference/index.md)** describes the JavaScript and TypeScript API. The **[runtime HTTP API](https://cognitio-agent.mintlify.site/http-api/overview.md)** is for advanced integrations that operate a server directly; you can use the SDK without learning that protocol.

Need help? Visit [troubleshooting](https://cognitio-agent.mintlify.site/troubleshooting.md) or email [ugurlu.oozgur@gmail.com](mailto:ugurlu.oozgur@gmail.com).


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