Skip to main content

Securing AI Agents and Agent API Keys

Use the @secureAiAgent decorator to designate a function as securing a given agent. Use Agent API Keys to bypass security methods and avoid needing App API Keys.​

Securing your data is vital when using the Squid Client to create AI agents and enable chatting. The AI agent and the chats conducted with them can contain sensitive information, so it's crucial to restrict access and updates to prevent unauthorized usage or modification.

Unless an AI agent has been set to public, access will be restricted by default and won't work without explicit rules that set access permissions. (Feel free to try it!)

Squid provides a @secureAiAgent decorator that you can use to set security rules. These rules prevent unauthorized users from updating agents or conducting unauthorized chats, protecting the integrity of your data.

tip

Before trying to secure the AI agent, make sure the public setting of the agent you want to secure is toggled to OFF and that you've set up your backend, as this will be required to set security rules for your AI agent.

Securing chats​

To manage chat permissions, use the @secureAiAgent decorator. To open up chat for all users to all agents, add the following to your backend:

import { secureAiAgent, SquidService } from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @secureAiAgent()
  allowChat(): boolean {
    return true;
  }
}

To restrict chat only to authenticated users, use the Squid backend's isAuthenticated() method. This method returns a boolean indicating whether the client attempting to take an action is authenticated.

@secureAiAgent()
allowChat(): boolean {
  return this.isAuthenticated();
}

Opening or closing access to all of your agents is very broad though, so it is recommended that you specify the Agent ID for which you are configuring the access security. To do so, add the AI agent's ID to the @secureAiAgent decorator:

@secureAiAgent('AGENT_ID')

Conditional checks​

The API allows the client to send various options with their query, which can be something you want to lock down.

For example, the query options are able to specify using a different AI model than the one that was set for the agent. To lock that down, this method checks if options.model is given a value, and fails if it does.

@secureAiAgent()
immutableModel(context: SecureAiAgentContext): boolean {
  if (context.options?.model !== undefined) {
    // Don't allow overriding the model that was configured for the agent.
    return false;
  }
  return this.isAuthenticated();
}

There are many other options, and if you are unsure where to begin, then the safest thing to do is to disallow any options at all.

@secureAiAgent()
immutableAgent(context: SecureAiAgentContext): boolean {
  const options = context.options || {};
  if (Object.keys(options).length > 0) {
    // Don't allow any options
    return false;
  }
  return this.isAuthenticated();
}

To learn more, take a look at all of the other options you can block or allow.

Agent API Keys​

Agents can have their own API keys that can be used instead of App API Keys to bypass agent security rules. App API Keys can provide full access to your entire application, including destructive actions, so it can be useful to use an API Key that is scoped to an Agent to minimize the security risk.

Limitations​

  • Agent API Keys can only be used for Agent based actions, which does limit their usefulness.
  • Agent API Keys are ignored if an App API Key is present.

Usage​

To use an Agent API Key, pass it in as part of the options array when creating an Agent Client.

/**
 * Note the lack of App API Key when creating the Squid instance. This is important as passing an API Key here will cause the Agent API Key to be ignored.
 */
const squid = new Squid({
  appId: 'YOUR_APP_ID',
  region: 'YOUR_REGION',
  environmentId: 'dev',
  squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
});

const agentClient = await squid
  .ai()
  .agent('banking-copilot', {
    apiKey: process.env.SQUID_AGENT_API_KEY,
  });