Scoopika for the Web

This guide provides a walkthrough for integrating Scoopika into your web application, covering both server-side and client-side setup.

​

Key concepts

Scoopika Endpoint: A central container that handles API requests related to Scoopika functionalities. It can be easily added to an API route and should work with any web frameworks that supports HTTP streaming.

AI Agents: Personalized LLM-powered assistants. Created from the platform and executed on your servers.

Tools: Custom functions that extend the capabilities of agents. Allowing the agent to call the function to perform actions or fetch data based on the context.

Client-side Actions: A special type of tools defined and executed on the client-side, enabling agents to safely execute tools on the client-side in real-time (example: clicking a button).

We provide examples for integrating Scoopika with a lot of frameworks, check the Usage page for more info based on the framework you’re using.

However, This example shows how to use Scoopika in a simple Express server (for its simplicity).

​

Server-Side Integration

​

1. Installation

The first step involves installing the Scoopika package for server-side use:

npm install @scoopika/scoopika

​

2. Initialize

Let’s initialize Scoopika and set up your agents. Here’s a basic example:

import { Scoopika, Endpoint } from "@scoopika/scoopika";

// Initialize Scoopika instance
const scoopika = new Scoopika({
	token: "YOUR_SCOOPIKA_TOKEN", // Replace with your token or set `SCOOPIKA_TOKEN` in your env
	store: "REMOTE_STORE_ID", // For persistent history (optional)
	keys: {...} // Replace with your keys
});

// Create endpoint to handle requests
const scoopikaEndpoint = new Endpoint({
	scoopika,
	agents: ["AGENT_ID-1", "AGENT_ID-2"]
});

export default scoopikaEndpoint;

Refer to the following resources for more details:

Initialize Scoopika.

Scoopika Endpoint.

​

Custom setup

For more advanced scenarios where you want to add tools to your agents, the agents property can take a function that allows for custom agent setup logic and returns an array of agents:

import { Scoopika, Agent, Endpoint } from "@scoopika/scoopika";

const scoopika = new Scoopika({...});

// Create endpoint to handle requests
const scoopikaEndpoint = new Server({
	scoopika,

	// use custom setup function
	agents: async (scoopika) => {
		const myAgent1 = new Agent("AGENT_ID-1", scoopika);
		const myAgent2 = new Agent("AGENT_ID-2", scoopika);

		// do anything you want here... like:

		// Pass agent2 as tool to agent1
		await myAgent1.addAgentAsTool(myAgent2);

		// Add other tools to agent1
		myAgent1.addTool(...);

		return [myAgent1, myAgent2]; // return array of agents
	}
})

export default scoopikaEndpoint;

​

3. Add API Route

Now, create an API route within your framework (e.g., Express) to handle Scoopika requests using the Scoopika Endpoint. This example demonstrates usage with Express:

import express from "express";
import cors from "cors";
import scoopikaEndpoint from "./scoopika"; // path to your Scoopika endpoint

const app = express();
app.use(express.json()); // Required middleware
app.use("/scoopika", cors()); // Allow cors (adjust this as you want)

// has to be 'post' route
app.post("/scoopika", (req, res) => {
	scoopikaEndpoint.handleRequest({
		request: req.body,
		stream: (s) => res.write(s),
		end: () => res.end()
	});
})

app.listen(4149, () => {
	console.log("Running on port 4149");
});

This route will now be able to handle running anything related to Scoopika from running agents or boxes, getting their info, and managing history sessions. Refer to the Scoopika Endpoint documentation for more info.

​

Client-side

​

1. Installation

On the client-side, install the Scoopika client package:

npm install @scoopika/client

​

2. Initialize and Run

Now you can initialize a Scoopika client, an agent, and run it:

import { Client, Agent } from "@scoopika/client";

const client = new Client(
	"http://127.0.0.1:4149/scoopika" // The exact url to your scoopika API.
);

const agent = new Agent("AGENT_ID", client);

(async () => {

	const response = await agent.run({
		inputs: { message: "Hello!" },
		hooks: { // real-time streaming hooks are supported
			onToken: (t) => console.log(t)
		}
	});

	console.log(response);
})();

This example shows almost all the actions you can do on the client-side:

// Create new chat session
const session = await client.store.newSession({
	user_id: "USER_1" // set optional user ID
});
console.log(session); // StoreSession

// Load agent data
const agentData = await agent.load();
console.log(agentData.name); // string

// Run agent
const response = await agent.run({
	options: {
		session_id: session.id,
		voice: true // allow audio response
	},
	inputs: {
		message: "Hello!",
	},
	hooks: { // real-time streaming hooks are supported
		onToken: (t) => console.log(t)
	}
});
console.log(response); // AgentResponse

// List user sessions
const userSessions = await client.store.listUserSessions("USER_1");
console.log(userSessions); // string[]

// Get chat session messages
const messages = await client.store.getSessionMessages(userSessions[0]);
console.log(messages); // RunHistory[] (in this example there should be 2 items. one for the user request, and one for the agent response)

// Delete session
const deleted = await client.store.deleteSession(session.id);
console.log(deleted); // boolean

For comprehensive instructions and API reference, refer to the Scoopika Client documentation.

​

Tools (optional)

Scoopika allows you to equip your agents with tools, extending their capabilities. These tools can be defined and executed on either the server-side or client-side.

For full docs on tools, refer to the Tools documentation.

​

API Tools

API tools are added from the platform with no-code. they can be used to give agents the ability to call external APIs. you define the API url, headers, body, and method. the tool also takes inputs that are passed from the agent when calling it, and they can be used in the tool’s url or request body.

Learn more about API tools.

​

Server-side Tools

Server-side tools are custom functions that you add to agents on the server. You can define the tool’s arguments using a Zod schema, allowing Scoopika to validate the agent’s outputs when calling the tool, ensuring stability and type safety. The results returned by this function are sent back to the agent for further processing (learn more about tools).

To add tools from the server-side, you need to use a custom agents setup function:

import { Scoopika, Endpoint, Agent } from "@scoopika/scoopika";
import tool from "./tools/my_tool";

const setupAgents = async (scoopika: Scoopika) => {
	const myAgent = new Agent("AGENT_ID_1", scoopika);

	// Add the tool (example)
	myAgent.addTool({
		name: "get_document_info",
		description: "Get information about a document",
		parameters: z.object({
			id: z.string()
		}),
		execute: ({ id }) => {...} // tool logic here
	});

	return [myAgent]; // return array of agents
}

const scoopika = new Scoopika();
const endpoint = new Endpoint({
	scoopika,

	// use custom setup function
	agents: setupAgents
});

export default endpoint;

​

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 called Client-side actions.

Key Difference

Unlike server-side tools, results from client-side actions are not returned to the agent. This means they cannot be used for data retrieval but are ideal for allowing the agent to perform actions on the client-side in real-time, such as clicking buttons or typing in inputs. Refer to the Client-side actions documentation for details and examples.

Adding Client-side Actions

The process for adding client-side actions is similar to server-side tools. You just define a schema and pass a custom function from the client-side as a tool.

Example:

import scoopikaClient from "@/lib/scoopika"; // path to your scoopika client instance
import { Agent } from "@scoopika/client";

const agent = new Agent("AGENT_ID", scoopikaClient);

agent.addClientAction({
	name: "sort_documents",
	description: "",
	... // the same logic applies to the client side
});

Remember: When the agent calls a client-side action, it executes on the client-side in real-time, enabling dynamic interactions within the web application.

See how to build your tools for more information on how to define your tools schema.

​

Next steps

Now that you have setup Scoopika on both the server-side and the client-side, the fun part starts. Memory is managed for you, streaming is managed for you, validation is also managed for you, what you gonna do? well just focus on building your application and unique features. good luck!

We strongly recommend you check the full docs and API reference for both Packages.