An agent can't reach a service because a secret is missing Troubleshooting

When an agent needs to call an outside service — a payment provider, a weather API, a webhook — it uses a secret you store for it: an API key or token kept in a secure vault. If that secret is empty, or its name doesn't match what the agent expects, the call can't be made and the agent's task fails. This guide walks you through fixing that.

How secrets work

Each agent has a Secrets tab under the Configure section of its detail page. A secret has a name, a value, and an optional description. The value is encrypted, hidden after you save it, and injected securely only at run time — it never enters the agent's reasoning. The agent references a secret only by its name, written as {{secret:NAME}}.

Because the agent points at a secret by name, two things must both be true for an external call to succeed: the secret must exist under the exact name the agent references, and it must hold a real, current value.

Note: An agent with a secret referenced but never filled in behaves the same as one with no secret at all — the outside service simply can't be reached.

Confirm the secret is the cause

If an agent reports that it couldn't complete a task that involves an outside service, check the Secrets tab first.

1. Open the agent and go to the Secrets tab under Configure.
2. Look at the list of secrets. Each one shows whether it is set or still empty.
3. If a required secret is missing from the list, or shows as empty, that is almost certainly why the call failed.

Add or fill in the secret

1. On the Secrets tab, choose to add a secret (or edit the existing empty one).
2. Enter the name exactly as the agent references it. This is the single most common point of failure — the name must match character for character, including capitalization.
3. Paste the value — the API key or token from the outside service.
4. Optionally add a description so you remember later what the value is for.
5. Save. The value is encrypted and hidden from view from that point on.

Getting the name right

The agent expects one specific name. If you aren't sure what it is, ask the AI builder on the agent's Build tab — for example, "What secret name do you use for the weather API?" The builder can tell you the exact name it references, and it can also request a secret from you directly with a fill-in card when it sets up a new external call.

Getting the value right

The value comes from the outside service itself, not from Praxivara. Sign in to that service's own dashboard, find its API keys or tokens section, and copy the key from there. If the key was recently rotated, revoked, or has expired, generate a fresh one and paste the new value in — an out-of-date key produces the same failure as a missing one.

Test the fix

After saving the secret, run the agent to confirm the external call now works.

1. Use the test run on the agent to trigger the task that failed before.
2. Confirm the agent reaches the service and completes the step.
3. If it still fails, re-check the secret name against what the agent references and verify the value is correct and active in the outside service.

Common causes at a glance

Tip: Storing a value here is safe. Secrets are encrypted, hidden after saving, and are never exposed in the agent's reasoning or output — they are used only to make the call at run time.