Prerequisite

  1. Scoopika account. create one here.
  2. Scoopika access token. generate one here.

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

​
Key concepts

Scoopika Container: A central component 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 on 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 executed 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:

scoopika.ts
import { Scoopika, Container } from "@scoopika/scoopika";

// Initialize Scoopika instance
const scoopika = new Scoopika({
	token: "YOUR_SCOOPIKA_TOKEN", // Replace with your token
	store: "REMOTE_STORE_URL", // For persistent history (optional)
	engines: {...} // Replace with your engines
});

// Create container to handle requests
const scoopikaContainer = new Container({
	scoopika,
	agents: ["AGENT_ID-1", "AGENT_ID-2"]
})

export default scoopikaContainer;

Refer to the following resources for more details:

Initialize Scoopika.

Scoopika Container.

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, Container } from "@scoopika/scoopika";

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

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

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

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

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

// Create container to handle requests
const scoopikaContainer = new Container({
	scoopika,
	agents: setupAgents
})

export default scoopikaContainer;
You can add boxes the same way you do with agents. check the Container docs for more info

​
3. Add API Route

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

import express from "express";
import scoopikaContainer from "./scoopika"; // path to your Scoopika container

const app = express();
app.use(express.json()); // Required middleware

app.post("/scoopika", async (req, res) => {
	await scoopikaContainer.handleRequest({
		request: req.body,
		stream: (s) => res.write(s),
		end: () => res.end()
	});
})

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

This scoopika 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 Container 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://localhost: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({
	inputs: {
		message: "Hello!",
		session_id: session.id
	},
	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 session runs (messages or history)
const runs = await client.store.getSessionRuns(userSessions[0]);
console.log(runs); // 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.

​
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 JSON 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.

Here’s an example of creating a server-side tool:

Example tool:

// Type-safe example

import { createToolSchema, FromSchema, JSONSchema } from "@scoopika/scoopika";

// Define the tool parameters schema
const toolParams = {
  type: "object",
  properties: {
    id: {
      type: "string",
      description: "The document ID to get info about",
    }
  },
  required: ["id"]
} as const satisfies JSONSchema;

// Define the tool inputs type (from the tool parameters)
export type ToolInputs = FromSchema<typeof toolParams>;

// Create the tool schema
const toolSchema = createToolSchema({
  name: "get_document_info",
  description: "Get information about a document",
  parameters: toolParams
});

// Define the tool function
function toolFunc(args: ToolInputs) {
  // Implement your tool logic here
}

const tool = {
  func: toolFunc,
  schema: toolSchema
};

export default tool;

Now in your server-side agent setup, you can equip an agent with this tool:

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

const setupAgents = async (scoopika: Scoopika) => {
	const myAgent = new Agent("AGENT_ID_1", scoopika);
	myAgent.addTool(tool.func, tool.schema); // Add the tool

	return [myAgent];
};

​
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(toolFunc, toolSchema);

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, you can start trying the advanced functionalities Scoopika offers, like adding tools to agents, using agents to extract structured data, adding agents as tools to other agents so they can call each other when needed, and much more!

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

Was this page helpful?

Express