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

# secrets • AI Agent SDK

> First-class secret references for credential fields (Issue #3102).

# secrets

AI Agent

First-class secret references for credential fields (Issue #3102).

Provides a lightweight, protocol-first contract so that any credential field
(bot token, Slack app token, WhatsApp verify token, API keys) can be sourced
from an environment variable, a mounted secret file, or a command / secret
manager — instead of being committed as plaintext or exposed as a process-wide
environment variable.

Design goals (kept deliberately lightweight — stdlib only, no heavy imports):

* `SecretRef` — a typed, immutable reference describing *where* a secret lives.
* `SecretInput` — `str | SecretRef | dict` so plaintext and `${ENV}` stay
  fully backward compatible; the reference form is purely additive.
* `SecretResolver` — a pluggable protocol; the built-in resolver handles the
  `env` / `file` / `exec` sources with the stdlib alone.
* `register_secret_for_redaction` / `redact_secrets` — a process-wide
  registry so resolved secret values can be scrubbed from logs and errors.

The wrapper (`praisonai`) and channel adapters may register additional
resolvers (e.g. a Vault / AWS / GCP secret-manager resolver) without importing
anything heavy into core.

## Import

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import secrets
```

## Classes

> [card] [SecretRef](https://praison.ai/docs/sdk/reference/praisonaiagents/classes/SecretRef.md)
>
> An immutable reference to a secret held outside the config file.

> [card] [SecretResolution](https://praison.ai/docs/sdk/reference/praisonaiagents/classes/SecretResolution.md)
>
> Outcome of resolving a :class:`SecretRef`.

> [card] [SecretResolver](https://praison.ai/docs/sdk/reference/praisonaiagents/classes/SecretResolver.md)
>
> Pluggable resolver contract. Implementations must not raise on a merely

> [card] [DefaultSecretResolver](https://praison.ai/docs/sdk/reference/praisonaiagents/classes/DefaultSecretResolver.md)
>
> Stdlib-only resolver for the `env` / `file` / `exec` sources.

> [card] [OutboundRedactor](https://praison.ai/docs/sdk/reference/praisonaiagents/classes/OutboundRedactor.md)
>
> Overridable contract for scrubbing outbound text before dispatch.

> [card] [EgressGuardProtocol](https://praison.ai/docs/sdk/reference/praisonaiagents/classes/EgressGuardProtocol.md)
>
> Contract for the wrapper's secret-egress firewall.

## Functions

> [card] [register\_resolver()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/register_resolver.md)
>
> Register a custom resolver for a source name (e.g. `vault`).

> [card] [resolve\_secret()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/resolve_secret.md)
>
> Resolve a credential input to a :class:`SecretResolution`.

> [card] [is\_secret\_ref()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/is_secret_ref.md)
>
> True if `value` is a :class:`SecretRef` or its dict reference form.

> [card] [register\_secret\_for\_redaction()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/register_secret_for_redaction.md)
>
> Register a resolved secret value so :func:`redact_secrets` masks it.

> [card] [redact\_secrets()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/redact_secrets.md)
>
> Replace every registered secret value in `text` with `[REDACTED]`.

> [card] [redact\_outbound()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/redact_outbound.md)
>
> Scrub secrets from text on its way to a chat user (safe-by-default).

> [card] [sentinelize()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/sentinelize.md)
>
> Return an opaque sentinel token standing in for `secret`.

> [card] [desentinelize()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/desentinelize.md)
>
> Substitute every known sentinel in `text` back to its real secret.

> [card] [has\_sentinel()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/has_sentinel.md)
>
> True if `text` contains a minted sentinel token.

### Constants

| Name | Value |
| - | - |
| `_VALID_SOURCES` | `('env', 'file', 'exec')` |
| `AVAILABLE` | `'available'` |
| `UNAVAILABLE` | `'configured-but-unavailable'` |
| `MISSING` | `'missing'` |
| `_REDACTED` | `'[REDACTED]'` |
| `_MIN_REDACT_LEN` | `4` |
| `_CREDENTIAL_SHAPE_PATTERNS` | `('\\bsk-(?:ant-\|proj-)?[A-Za-z0-9_-]{16,}\\b', '\\bAKIA[0-9A-Z]{16}\\b', '\\bgh[pousr]_[A-Za-z0-9]{16,}\\b', '\\bgithub_pat_[A-Za-z0-9_]{22,}\\b', '\\bAIza[0-9A-Za-z_-]{35}\\b', '\\bxox[baprs]-[0-9A-Z...` |
| `_SENTINEL_PREFIX` | `'oc-sent-'` |


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