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

# Lifecycle and failure handling

> Close the resources your application owns and distinguish failed results from rejected operations.

For the TypeScript examples, use the [TypeScript setup](https://cognitio-agent.mintlify.site/installation.md#typescript-projects), including `"type": "module"` and the `tsx` runner.
An Agent, a Session handle and a runtime process have different lifetimes. Close the objects you create, and stop a shared runtime only when the application has finished with it.

| Construction | Who owns the runtime/client? | Cleanup |
| - | - | - |
| `new Agent()` or `query()` with no connection options | Process-wide default client | Close Agent handles; call `shutdown()` at application teardown. |
| `new Agent({ spawn: ... })` | That Agent owns a dedicated local client | `agent.close()` closes it and its runtime. |
| `new Agent({ client })` | The application that created the client | Close Agent, then close client when all borrowers finish. |
| `createAgentClient({ baseUrl })` | Server is externally owned | `client.close()` releases local resources, not the server. |

## Handle both forms of failure

Use the [quickstart](https://cognitio-agent.mintlify.site/quickstart.md) setup with `OPENAI_API_KEY`. Save this as `lifecycle.ts`; run `node --env-file=.env --import tsx lifecycle.ts`.

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

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  disallowedTools: ["*"],
  maxTurns: 2,
})
try {
  const result = await agent.run("Explain an API timeout in one sentence.", {
    signal: AbortSignal.timeout(60_000),
  })
  if (result.subtype !== "success") {
    console.error("Run did not succeed", result.subtype, result.error?.message)
    process.exitCode = 1
  } else {
    console.log(result.text)
  }
} catch (error) {
  if (isSdkError(error)) console.error("SDK operation failed", error.kind, error.message)
  else console.error(error instanceof Error ? error.message : String(error))
  process.exitCode = 1
} finally {
  await agent.close().finally(() => shutdown())
}
```

A provider or run limit can produce an unsuccessful terminal result, so a fulfilled promise is not enough to establish success. Setup, protocol, transport and lifecycle problems may reject instead. The `isSdkError` guard recognizes tagged SDK errors with kinds such as `configuration`, `binary`, `transport`, `protocol`, `closed` and `session_conflict`. Do not match human-readable messages to make policy decisions.

## Share a client intentionally

This separate example owns one local runtime and lends its client to an Agent. No process-global `shutdown()` is needed for that owned client.

```ts theme={null}
import { Agent, createAgentClient } from "cognitio-agent-sdk"

const client = await createAgentClient({ spawn: { port: 0 } })
const agent = new Agent({ client, model: "openai/gpt-4.1-mini", disallowedTools: ["*"] })
try {
  const session = await agent.createSession({ title: "Two turns" })
  const first = await session.send("Remember that the database is PostgreSQL.")
  if (first.subtype !== "success") throw new Error(`First turn ended: ${first.subtype}`)
  const second = await session.send("Which database did I mention?")
  if (second.subtype !== "success") throw new Error(`Second turn ended: ${second.subtype}`)
  console.log(second.text)
} finally {
  await agent.close().finally(() => client.close())
}
```

`Session.send()` returns `ResultMessage` and takes a single prompt argument in v2. Check `subtype`; it does not have the facade's `RunResult.isError` convenience field. Low-level `Session.stream()` also has no caller-supplied `signal` option in v2. Use `session.interrupt()`/`abort()` to stop an active turn, or the facade’s `Agent.run()`/`stream()` signal support when that fits your application.

A default isolated runtime stores state in scratch storage removed when its owner closes. `session.close()` normally releases the local handle without deleting the server session, but closing the runtime's owner can remove the entire scratch database. See [sessions](https://cognitio-agent.mintlify.site/concepts/sessions.md) before designing persistence.

## Cancel and finish cleanup

Pass an `AbortSignal` to `Agent.run()` or `Agent.stream()`. For an existing low-level Session, call `session.interrupt()`/`abort()` or close its owner. Breaking a `for await` loop returns the iterator and aborts its owned turn. Abandoning an iterator without returning or aborting it can leave work active.

Repeated `close()` calls are safe. Closing during active work requests cancellation and waits for bounded cleanup. Cleanup itself can fail; an aggregate error can contain multiple underlying failures. The `finally` chains above ensure the outer owner is still closed if handle cleanup rejects.

Call `shutdown()` once at the boundary where the application no longer needs any default Agent. Do not call it after each HTTP request in a service that has other concurrent default Agents. It does not close clients you constructed and injected yourself.

## Retry side effects carefully

A lost connection does not prove a tool did not execute. Before replaying a task, inspect the persisted conversation and your application's operation state. Add idempotency keys or duplicate detection to custom tools that send messages, charge accounts or modify external services.

Configuration/state isolation does not sandbox the host filesystem, subprocesses or network. Custom callbacks execute in your SDK process even when the runtime is isolated or remote. Keep their privileges and cleanup under application control.

Custom `spawnProcess` adapters are an advanced escape hatch: they must implement the documented child-process streams, lifecycle events, kill behavior and exit/signal state. Prefer the bundled spawn path unless your deployment needs a custom process owner.


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