Where a key may be sent

The rule

A tool uses a key by writing {{secrets.NAME}} in its address, headers or body. Every call is checked after the placeholders are filled, just before it goes out:

Redirects are checked the same way. A redirect is followed only to a listed host, five hops at most.

How a key gets its hosts

You rarely set the list by hand. The first time you save a tool that uses a key, the key is pinned to every host it is already sent to in the workspace:

• the hosts in this save,
• this agent's draft and every stored version of it, so a conversation still on an older version keeps working,
• and, for a workspace key, every other agent that sends it, archived agents included.

So the first pin never cuts off a tool that was working. You typed those hosts, so saving is the consent: there is no extra dialog. The pin is written only after the save succeeds, and two first saves at the same moment keep both their hosts.

Only a destination the save adds is checked. An unrelated edit to an agent is never blocked by a key it already uses.

Write the host out in full

The host decides where a key goes, so a tool that sends a key must start its address with the scheme and a written-out host. A placeholder cannot build them.

A tool that sends no key may keep placeholders anywhere, as before. Only a new or changed tool is checked when you save. An older tool you have not touched still saves, but its calls that use a key are refused until its address is written out in full.

Addresses are saved in one spelling: trimmed, the scheme and host in lower case, and a default port (:443 for https) dropped. So HTTPS://API.Example.com:443/x and https://api.example.com/x are the same host.

What gets refused, and what it says

Every refusal names the fix. The messages are exactly these:

A refused call is an ordinary tool answer, so the agent explains it to the person and the conversation goes on. The key's value never appears in it, and the turn's tool event for that call ends with ok: false.

Send a key to another host

Usually, use a separate key. One key per service keeps each key's reach small, and a leak of one does not expose the other. Create the second key under its own name and use that name in the new tool.

When one key really serves two hosts, add the host on purpose from the SDK. Saving a tool never adds one.

// pin it when you create it
const key = await ws.secrets.create({
  name: 'HELPDESK_TOKEN',
  value: process.env.HELPDESK_TOKEN,
  allowedHosts: ['api.helpdesk.example.com'],
});

// later: replace the list (it is not a merge, so name every host)
await key.setAllowedHosts(['api.helpdesk.example.com', 'uploads.helpdesk.example.com']);
key.allowedHosts;   // ['api.helpdesk.example.com', 'uploads.helpdesk.example.com']

// [] unpins it: the next tool saved with it pins its own host again
await key.setAllowedHosts([]);

Write the host alone, with no https:// and no path. At most 20 hosts per key. A wrong entry is refused with the reason, for example: allowedHosts: "https://api.example.com" is not a host. Write the host alone, like "api.example.com", with no https:// and no path.

Handling the refusal in code

import { SecretHostNotAllowed } from '@cerebro-labs/agentnava-sdk';

try {
  await agent.update({ httpTools });
} catch (err) {
  if (err instanceof SecretHostNotAllowed) {
    err.code;          // 'secret_host_not_allowed'
    err.secret;        // 'HELPDESK_TOKEN'
    err.host;          // 'api.other.example.com'
    err.allowedHosts;  // ['api.helpdesk.example.com']
  }
  throw err;
}

SecretHostNotAllowed is an AgentNavaError, so code that branches on err.code keeps working.

An end user's token

const key = await ws.endUser(user.id).secrets.create({
  name: 'HELPDESK_TOKEN',
  value: token,
  allowedHosts: ['api.helpdesk.example.com'],
});

See Credentials for your users.

In the app

• Where a key may go is fixed the first time a tool that uses it is saved. The app cannot change it.
• To send a key to another host, add a separate key on the Secrets tab and use it in the new tool.
• The Agent Builder never changes where a key goes. If a change it makes is refused because a key is only sent to another host, it tells you to add a separate key.
• A token you type into an HTTP tool must be at least 8 characters.