Getting Started

​

What are Tools

Tools are APIs or custom functions the agent can use to perform actions or fetch data. Once you equip an agent with a tool, it will use it automatically when it needs to based on context.

You can turn any API or function into a tool the agent can use, you just need to define the schema of the inputs the tool expects to receive from the LLM.

​

API Tools

Those tools are defined from the platform with no-code, refer to this page for more info.

​

Tool Schema

Each tool is defined by a schema with the following properties:

​

When to Use Tools

Imagine creating an agent that assists users with managing tasks. You can equip this agent with a tool named add_task that handles adding tasks to a to-do list. When a user instructs the agent to add a task, the agent calls this tool, providing the relevant details (task description and deadline) as arguments based on the tool’s schema.

In this example, you can add this tool to your agent like this:

import { z } from "zod";

agent.addTool({
	name: "add_task",
	description: "Add user task to be done later",
	parameters: z.object({
		task: z.string().describe("What is the task to be added"),
		deadline: z.string().describe("By when should this task be done").optional()
	}),
	execute: ({ task, deadline }) => {...} // the tool logic goes here
});

So let’s imagine the users says:

I need to set up a blog by tomorrow, could you add that to my tasks?

Then the agent will call the tool with the right arguments to add the task, in this examples the arguments would look like this:

{
	"task": "Setup a blog",
	"deadline": "By tomorrow"
}

Tool Arguments - Generative Power

It’s important to note that tool arguments can be generative. This means the AI model powering the agent might generate values for certain arguments based on its understanding of the user’s request.

​

Equipping Agents with Tools

​

Server-side Tools

• These are custom functions defined and executed on your server.
• You can leverage JSON schemas to define the tool’s arguments, enabling Scoopika to validate the agent’s outputs when calling the tool. This ensures stability and type safety.
• The function’s returned results are sent back to the agent for further processing.

The provided code snippet showcases a type-safe approach using TypeScript and generates types from the tool schema:

import { z } from "zod";

agent.addTool({
	name: "search_the_web",
	description: "Search the web given a search query",
	parameters: z.object({
		query: z.string().describe("The search query")
	}),
	execute: ({ query }) => {
		console.log(query); // string a 100%
	}
});

The agent.addTool method is used to add tools to an agent, For adding tools to boxes, refer to this documentation.

​

Client-side Actions (Client-side Tools)

Similar to server-side tools, you can equip agents with tools defined and executed on the client-side. These are known as Client-side actions.

Key Distinction

Unlike server-side tools, results from client-side actions are not returned to the agent. This makes them unsuitable for data retrieval but ideal for enabling agents to perform real-time actions on the client-side, such as simulating user interactions or manipulating the DOM.

Adding Client-side Actions

The approach for adding client-side actions is just the same as adding tools from the server-side, the only difference is that on the client-side we use agent.addClientAction instead of agent.addTool:

import { z } from "zod";

agent.addClientAction({
	name: "sort_documents",
	description: "Sort the user documents",
	execute: ({ order }) => {...}, // action logic goes here
	parameters: z.object({
		order: z.enum(["asc", "desc"]).describe("The order to sort documents in based on date")
	})
});

​

Adding a lot of Tools

Adding a lot of tools to your agent is usually not a good practice as it makes it hard for the agent to choose the right tools and they take a lot of tokens from the LLMs context window. But not with Scoopika…

If you equip your agents with more than 5 tools, Scoopika will select the most suitable 5 tools to pass to the agent based on the context of the conversation.