> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lasscyber.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK overview

> Two official SDKs — Python and TypeScript — that share one OpenAPI contract and one ergonomic surface.

Agnes ships two official SDKs:

* **Python** — [`agnes-security`](https://pypi.org/project/agnes-security/) on PyPI.
* **TypeScript** — [`@lasscyber/agnes-security`](https://www.npmjs.com/package/@lasscyber/agnes-security) on npm.

Both wrap the same HTTP API (`https://api.lasscyber.com`), share one
OpenAPI contract, and expose the same ergonomic surface:

* `Agnes` / `AsyncAgnes` (Python) and `Agnes` (TypeScript) — the
  primary client.
* `analyze()` — single hero call that returns a typed `Decision`.
* `guard()` — context that wraps an LLM call with `check_input` /
  `check_output` and auto-flips inbound ↔ outbound policies.
* `PolicyBuilder` — fluent builder for combined policies in code.
* Typed errors mapping 1:1 to the canonical
  [error codes](/errors/overview).
* Pagination helpers for resource list endpoints.
* A `raw` / `agnes.raw` escape hatch that exposes the auto-generated
  low-level client for any endpoint not yet wrapped by the ergonomic
  surface.
* Optional **OpenAI drop-in** integration via a separate subpath
  export.

## Surface comparison

| Concept        | Python                                                          | TypeScript                                                        |
| -------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
| Client         | `Agnes()` / `AsyncAgnes()`                                      | `new Agnes()`                                                     |
| Analyze        | `agnes.analyze("...", policy="...")`                            | `await agnes.analyze("...", { policy: "..." })`                   |
| Guard          | `with agnes.guard(policy="...") as guard:`                      | `const guard = agnes.guard({ policy: "..." })`                    |
| Policy builder | `PolicyBuilder("name").prompt_injection_jailbreak(...).build()` | `new PolicyBuilder("name").promptInjectionJailbreak(...).build()` |
| Pagination     | `for x in agnes.policies.list(): ...`                           | `for await (const x of agnes.policies.list()) { ... }`            |
| Errors         | `Blocked`, `RateLimitError`, ...                                | `Blocked`, `RateLimitError`, ...                                  |

The naming convention is the standard split:

* **Python** — `snake_case` everywhere. Canonical analyzer names use
  underscores (`prompt_injection_jailbreak`).
* **TypeScript** — `camelCase` everywhere. Canonical analyzer names
  drop the dashes (`promptInjectionJailbreak`).

Both SDKs translate to the wire-format server keys at request time.

## Choosing an SDK

* **Python** for backend services, ML pipelines, scripts, and
  notebooks. Both sync (`Agnes`) and async (`AsyncAgnes`) clients are
  shipped; pick whichever matches your service.
* **TypeScript** for browser apps (your dashboard talking to your
  service that wraps Agnes), server-side Node, edge runtimes
  (Cloudflare Workers, Vercel Edge, Deno, Bun), and front-end build
  pipelines. The default entry is fully isomorphic.

You should **not** put an `ak_*` Agnes API key into a browser bundle —
treat keys as secrets. The TypeScript SDK's edge-runtime support is
about server-side / worker-side environments, not "drop the key in
your React app".

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install agnes-security
  ```

  ```bash TypeScript theme={null}
  npm install @lasscyber/agnes-security
  # or pnpm add @lasscyber/agnes-security
  # or bun add @lasscyber/agnes-security
  ```
</CodeGroup>

## Authentication

Both SDKs read `AGNES_API_KEY` from the environment by default. See
[Authentication](/get-started/authentication) for the full table of
ways to pass keys, including `Agnes-Version` pinning.

## Compatibility

* **Python:** 3.10+ supported. Type stubs ship with the package.
* **TypeScript:** Node 20+, browsers, Deno, Bun, Cloudflare Workers.
  No Node-specific imports in the default entry.

The OpenAI integrations are **optional extras** behind subpath imports;
callers who never use them pay zero bundle / dependency cost.

<CodeGroup>
  ```bash Python theme={null}
  pip install "agnes-security[openai]"
  ```

  ```typescript TypeScript theme={null}
  import { AgnesGuardedOpenAI } from "@lasscyber/agnes-security/integrations/openai";
  ```
</CodeGroup>

## Versioning

The SDKs follow Semantic Versioning, and each language SDK versions
independently from the server's date-based API contract. See
[Versioning](/sdks/versioning) for the full lifecycle and the
analyzer-name evolution rules.

## Where next

* [Python SDK](/sdks/python) — quickstart, errors, pagination,
  OpenAI drop-in.
* [TypeScript SDK](/sdks/typescript) — same content for the
  TypeScript world.
* [Versioning](/sdks/versioning) — SemVer for SDKs, dates for the
  server.
* [Sandbox mode](/testing/sandbox-mode) — exercise either SDK in CI
  without billing.