Agents and query

Run a task, reuse an agent profile, and choose the right conversation API.

An Agent combines a model, instructions, tools, and limits. Give it a task and the SDK runs the model/tool loop until the model finishes or a limit stops it. Cognitio starts its bundled runtime automatically; you do not need a separate CLI installation.

An Agent is a reusable configuration, not a conversation. Each run() or stream() starts a new session. Use sessions when later messages should remember earlier ones.

​

Run a task

This complete example checks the provider key, sends a short prompt, validates the terminal outcome, and closes its runtime. The explicit spawn.env supplies the key and gives this Agent its own local runtime. Isolation is already enabled by default.

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

const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) throw new Error("Set OPENAI_API_KEY before running this example.")

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  instructions: "Explain technical concepts clearly in at most three sentences.",
  spawn: { env: { OPENAI_API_KEY: apiKey } },
  disallowedTools: ["*"],
  maxTurns: 1,
  maxBudgetUsd: 0.03,
})

try {
  const result = await agent.run("What is a database index?", {
    signal: AbortSignal.timeout(60_000),
  })
  if (result.isError) throw new Error(`Agent ended: ${result.subtype}`)
  if (!result.text.trim()) throw new Error("The model returned no text.")
  console.log(result.text)
  console.log({ sessionId: result.sessionId, turns: result.turns })
} finally {
  await agent.close()
}

disallowedTools: ["*"] makes this a text-only task. Remove it or choose a nonempty allowedTools list when the task needs built-in tools or your own functions.

​

Run the examples

The guides use TypeScript with top-level await. In a Node.js 22 project, install:

npm install cognitio-agent-sdk@2.0.1
npm install --save-dev tsx typescript @types/node
npm pkg set type=module

Save a complete example as agent.ts. Create a .env file containing your OPENAI_API_KEY, add .env to .gitignore, then run:

node --env-file=.env --import tsx agent.ts

Use the quickstart for the initial provider setup. The cookbook also includes copyable JavaScript projects that need no TypeScript runner. Provider requests incur usage on your account; maxBudgetUsd is an estimated stopping threshold, not a prepaid spending cap.

​

Choose an API

API	Use it when	Conversation behavior
agent.run(prompt)	You want one final result.	Creates a fresh session and collects its stream.
agent.stream(prompt)	You want text and tool events while work runs.	Creates a fresh session and returns an async iterator.
agent.createSession()	You want a chat or a sequence of related tasks.	Returns a handle you can send multiple turns to.
query({ prompt, options })	You want a one-shot stream without keeping an Agent variable.	Owns a temporary Agent with the supplied options.
createAgentClient()	Your service manages connections and session storage directly.	Exposes session create, resume, fork, list, and delete operations.

For example, a second agent.run("What did I just ask?") does not see the first run. Configuration is shared, conversation history is not. Separate sessions can run concurrently; a single session accepts one active query at a time.

​

Check completion, not just transport success

agent.run() returns a RunResult: text, isError, subtype, session identifiers, turn count, duration, and optional usage/cost/structured output. A completed request can still have an unsuccessful terminal result.

subtype	Meaning
success	The turn completed normally.
error_max_turns	The assistant turn limit was reached.
error_max_budget	Reported estimated usage reached the budget.
error_aborted	The turn was interrupted.
error_max_structured_output_retries	The schema retry limit was reached.
error_during_execution	Execution failed; inspect error?.message.

Setup, connection, and lifecycle errors can also throw. Keep cleanup in finally, including when you reject a terminal result.

​

One-shot query

This alternative owns and closes its temporary Agent. Supplying spawn gives it a dedicated runtime that closes when iteration finishes, throws, or is returned early.

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

const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) throw new Error("Set OPENAI_API_KEY before running this example.")

const stream = query({
  prompt: "Explain a database index in one sentence.",
  options: {
    model: "openai/gpt-4.1-mini",
    spawn: { env: { OPENAI_API_KEY: apiKey } },
    disallowedTools: ["*"],
    maxTurns: 1,
    maxBudgetUsd: 0.03,
    signal: AbortSignal.timeout(60_000),
  },
})
try {
  for await (const message of stream) {
    if (message.type !== "result") continue
    if (message.result.subtype !== "success") {
      throw new Error(`Query ended: ${message.result.subtype}`)
    }
    console.log(message.result.text)
  }
} finally {
  await stream.close()
}

​

Runtime ownership

How you construct the Agent	Who closes the connection?
No spawn, baseUrl, client, control, or workspaceId	Agents share a process-wide local client. Close each Agent, then call exported shutdown() at application teardown.
Explicit spawn, as in these examples	The Agent owns a dedicated local client; agent.close() stops it and removes its temporary state.
baseUrl	The Agent owns its connection; closing it does not stop the remote server.
An injected client	The caller owns it. Neither agent.close() nor shutdown() closes that borrowed client.

Explicit control or workspaceId connection options also select a dedicated local client when no baseUrl or injected client is supplied. The Agent closes that dedicated client.

Local isolation separates runtime configuration, credentials, and state from your usual installation. It does not sandbox tool access to files, processes, or the network. Choose tool permissions for the work your application permits. For service shutdown patterns, see lifecycle.