AI functions

AI functions enhance and extend AI agents with custom functionality

When configuring your AI agents or AI assistants, you might find that certain questions require specific responses that are difficult to configure through instructions. For example, you might have industry-specific formulas that the model isn't familiar with. Or you may want the agent to take an action in response to a specific prompt, such as updating the database.

In these cases (and many others), you can use Squid's AI functions. By extending a function in a Squid Service with the @aiFunction decorator, you can connect your agent to these functions, allowing you to customize each agent with the functionality it requires.

Because these functions are defined in a Squid Service in Typescript, they can access the full power of the Squid platform. This means customization of these functions is limitless.

How to create AI functions

AI functions take a description parameter, which is a string describing the function. This description is how the AI agent determines when to use the function, so it is important that it is clear and informative.

The following example uses the @aiFunction decorator to define a function that an AI agent can use:

Backend code

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

class AiService extends SquidService {
  @aiFunction<{ shipName: string }>(
    'This function returns the list of pirates in a ship. ' +
    'Call this function whenever the user asks about the crew of a ship.',
    [
      {
        name: 'shipName',
        description: 'The name of the ship',
        type: 'string',
        required: true,
      }
    ]
  )
  async listPiratesInAShip(params: { shipName: string }): Promise<string> {
    const { shipName } = params;
    if (shipName === 'Black Pearl') {
      return 'Jack Sparrow';
    }
    else if (shipName === "Queen Anne's Revenge") {
      return 'Black Beard';
    }
    return 'No ship found';
  }
}

To add the function to an AI agent, pass the function name with a call to ask as part of the options parameter:

const response = await squid
  .ai()
  .agent('AGENT_ID')
  .ask('Which pirate was captain of the Black Pearl?', {
    functions: ['listPiratesInAShip'],
  });

const assistantId = await createAssistant('YOUR_ASSISTANT_NAME', "YOUR ASSISTANT'S INSTRUCTIONS", ['listPiratesInAShip']);

Note

After deploying the backend, added AI Functions will appear under the Abilities section in the console and can be used directly by agents within the Agent Studio. See the Backend deployment guide for more info.

Using AI Function to update a database

You can also provide AI agents with functions to update a database. For example, the following function updates a specific section in a large document in the built-in no-sql Squid database:

Backend code

// Assume we have the following section id definitions
export const SECTION_IDS = ['introduction', 'background', 'methodology', 'results', 'conclusion'] as const;
export type SectionId = typeof SECTION_IDS[number];

  @aiFunction('Saves a section in a document', [
  {
    name: 'sectionId',
    type: 'string',
    description: 'Which section to update in the document',
    required: true,
    enum: [...SECTION_IDS],
  },
  {
    name: 'content',
    type: 'string',
    description: 'The content of the section',
    required: true,
  },
])
async saveSection(
  {
    sectionId,
    content,
  }: {
  sectionId: SectionId;
  content: string;
},
): Promise<string> {
  
  const docRef = this.squid.collection("documents").doc("my-doc");
  await docRef.update({ [sectionId]: content });
  return 'section saved: ' + sectionId;
}

Note here we also used enum to restrict the possible values for sectionId. This helps the AI agent understand what values are valid.

Passing parameters to the AI Function (via Agent Context)

You can also pass parameters to the AI function via the agent context. This is useful when you want to provide additional information to the function. For example, building on the previous sample, you might want to pass a document id to be updated in the database based on a user selection coming from the client:

Backend code

// Assume we have the following section id definitions
export const SECTION_IDS = ['introduction', 'background', 'methodology', 'results', 'conclusion'] as const;
export type SectionId = typeof SECTION_IDS[number];

// Assume we defined agent context as the following
interface DocumentIdAgentContext {
  documentId: string;
}

@aiFunction('Saves a section in a document', [
  {
    name: 'sectionId',
    type: 'string',
    description: 'Which section to update in the document',
    required: true,
    enum: [...SECTION_IDS],
  },
  {
    name: 'content',
    type: 'string',
    description: 'The content of the section',
    required: true,
  },
])
async saveSection(
  {
    sectionId,
    content,
  }: {
  sectionId: SectionId;
  content: string;
},
ctx: AiFunctionCallContext<unknown, DocumentIdAgentContext>,
): Promise<string> {
  const docRef = this.squid.collection("documents").doc(ctx.agentContext.documentId);
  await docRef.update({ [sectionId]: content });
  return 'section saved: ' + sectionId;
}

You can pass the parameters you need to the agent both via the squid chat widget (or via the client SDK), for example:

Client code

<squid-chat-widget
...
squid-ai-agent-chat-options={{
  agentContext: { documentId: "my_document_id" },
}}
...
>
</squid-chat-widget>

Next Steps

Want to see a more complex example of an AI function in action? Take a look at our AI home maintenance tutorial.