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

<Badge color="blue">AI Agent</Badge>

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 `$&#123;ENV&#125;` 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

<CardGroup cols={2}>
  <Card title="SecretRef" icon="brackets-curly" href="../classes/SecretRef">
    An immutable reference to a secret held outside the config file.
  </Card>

  <Card title="SecretResolution" icon="brackets-curly" href="../classes/SecretResolution">
    Outcome of resolving a :class:`SecretRef`.
  </Card>

  <Card title="SecretResolver" icon="brackets-curly" href="../classes/SecretResolver">
    Pluggable resolver contract. Implementations must not raise on a merely
  </Card>

  <Card title="DefaultSecretResolver" icon="brackets-curly" href="../classes/DefaultSecretResolver">
    Stdlib-only resolver for the `env` / `file` / `exec` sources.
  </Card>
</CardGroup>

## Functions

<CardGroup cols={2}>
  <Card title="register_resolver()" icon="function" href="../functions/register_resolver">
    Register a custom resolver for a source name (e.g. `vault`).
  </Card>

  <Card title="resolve_secret()" icon="function" href="../functions/resolve_secret">
    Resolve a credential input to a :class:`SecretResolution`.
  </Card>

  <Card title="is_secret_ref()" icon="function" href="../functions/is_secret_ref">
    True if `value` is a :class:`SecretRef` or its dict reference form.
  </Card>

  <Card title="register_secret_for_redaction()" icon="function" href="../functions/register_secret_for_redaction">
    Register a resolved secret value so :func:`redact_secrets` masks it.
  </Card>

  <Card title="redact_secrets()" icon="function" href="../functions/redact_secrets">
    Replace every registered secret value in `text` with `[REDACTED]`.
  </Card>
</CardGroup>

### Constants

| Name              | Value                          |
| ----------------- | ------------------------------ |
| `_VALID_SOURCES`  | `('env', 'file', 'exec')`      |
| `AVAILABLE`       | `'available'`                  |
| `UNAVAILABLE`     | `'configured-but-unavailable'` |
| `MISSING`         | `'missing'`                    |
| `_REDACTED`       | `'[REDACTED]'`                 |
| `_MIN_REDACT_LEN` | `4`                            |