How do I add Provely to my agent?

Add two lines to the code that starts your agent: the import and one instance. Set PROVELY_API_KEY. Write no other code.

Get your API key: sign in at app.provely.sh/account/api-keys, open API keys, and create a key. The dashboard shows the key once. Keep it in an environment variable, never in code. Or run provely login once on your machine: the SDKs then read the key that it stores.

import { Provely } from '@provely/sdk';

new Provely();

from provely import Provely

Provely()

What do I install?

Install two packages in each language. TypeScript needs @provely/sdk and @provely/instrumentations. Python needs provely and provely-instrumentations. The second package holds the plugins for the frameworks and the model SDKs.

The packages are private during the design-partner period. Your invitation states the registry and the access token.

Is the API key required?

Yes, unless a workload identity replaces it. With no credential, the instance does not start, and it states this error:

Set api_key or bearer_token. Use PROVELY_API_KEY or PROVELY_BEARER_TOKEN, or run provely login.

The SDK reads the key from the environment, or from a .env file in the working directory. An exported variable wins over the file. With neither, the SDK reads the key that provely login stored on the machine, for the same base URL only. Never put the key in a prompt or in the code.

Get your API key: sign in at app.provely.sh/account/api-keys, open API keys, and create a key. The dashboard shows the key once. Keep it in an environment variable, never in code. Or run provely login once on your machine: the SDKs then read the key that it stores.

In production, register a workload identity instead, and store no key. Set PROVELY_WORKLOAD_AUDIENCE to the audience that the Workload identities page shows. Read Run in production without a stored key.

• GitHub Actions: give the job permissions: id-token: write, and set PROVELY_WORKLOAD_AUDIENCE in its env.
• AWS Lambda or ECS: set PROVELY_WORKLOAD_AUDIENCE in the environment of the function or the task.

Where do the two lines go?

Put them in the module that starts the agent, before the first agent run. The first instance in a process loads the plugins. A later instance reads the same plugins.

How do I see what Provely did?

Provely writes one JSON line for each action to .provely/decisions.jsonl by default. Set PROVELY_DECISION_LOG to another path to move the log, or to off to stop it. Provely checks and fixes every call in both cases. The line holds ids and codes. It never holds an argument value.

export PROVELY_DECISION_LOG=provely-decisions.jsonl

Read How it works for the members of a line. Read Postures before you set PROVELY_GUARD_MODE=enforce.