Getting Started

The @palico-ai/react helps you communicate with your Palico agents, manage message history, and handle client-side tool calls in your React application.

Setup and Installation

The following guide assumes you are using NextJS for your React application.

Install Packages

Get started by installing the required packages:

npm install @palico-ai/client-js @palico-ai/react

Add API URL and Service Key to `.env`

Generate a service keyYou can generate a service key from your Palico App project directory

Local Instance
Production Instance

npm run palico generate apikey

npm run palico generate apikey -s <jwt-secret>

Add the entries to your NextJS .env file:

# replace with your Palico API URL
PALICO_AGENT_API_URL=http://localhost:8000
# replace with your Palico service key
PALICO_SERVICE_KEY=<your-service-key>

Setup Server-Side Authorization

We want to handle calling our Palico application in a server-side environment. To do this, we’ll create an API route in NextJS.Create a new file in src/app/api/palico/route.ts in your NextJS application and add the following code:

You should authorize the request before calling your Palico app.

import { createClient } from "@palico-ai/client-js";

export const maxDuration = 120;

export async function POST(req: Request) {
  await verifyUser(); // replace with your authorization logic
  const agentAPIURL = process.env.PALICO_AGENT_API_URL;
  const serviceKey = process.env.PALICO_SERVICE_KEY;
  if (!agentAPIURL || !serviceKey) {
    throw new Error("Missing Palico environment variables");
  }
  const request = await req.json();
  const client = createClient({
    apiURL: agentAPIURL,
    serviceKey: serviceKey,
  });
  const responseStream = await client.agent.chat({
    ...request,
    stream: true,
  });
  return responseStream.response;
}

Usage

You can use the useChat() hook to interact with your Palico agent in your React components.

import { useChat } from "@palico-ai/react";

const Assistant: React.FC = () => {
  const { messages, sendMessage } = useChat({
    agentName: "assistant",
    apiURL: "/api/palico", // the API route we created
  });

  const handleSendMessage = async (message: string) => {
    await sendMessage({
      userMessage: message,
    });
  };

  return (
    <div>
      {messages.map((message, index) => (
        <div key={index}>
          {message.sender} - {message.message}
        </div>
      ))}
      <input
        type="text"
        placeholder="Type a message..."
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            handleSendMessage(e.currentTarget.value);
            e.currentTarget.value = "";
          }
        }}
      />
    </div>
  );
};

Client-Side Tool Execution

You can handle client-side tool calls in your React application using the pendingToolCalls and addResult params from the useChat hook. Here’s an example of how you can handle client-side tool calls:

import { useChat } from "@palico-ai/react";

const Assistant: React.FC = () => {
  const { addResult, pendingToolCalls } = useChat({
    agentName: "assistant",
    apiURL: "/api/palico", // the API route we created
  });
  const { showDialog } = useDialog();

  if(pendingToolCalls.length > 0) {
    // handle client-side tool calls
    const toolCall = pendingToolCalls[0];
    if(toolCall.name === "askForConfirmation") {
      showDialog({
        title: "Confirmation",
        message: toolCall.parameters.message,
        onConfirm: () => {
          addResult(toolCall, {
            confirmed: true,
          });
        },
        onCancel: () => {
          addResult(toolCall, {
            confirmed: false,
          });
        },
      });
    } else if(/*... other tool calls */) {
      // handle other tool calls
    }
  }

  return (
    //... your UI
  )
};

API reference

`useChat()`

The useChat() hook returns an object with the following properties:

messages

Message[]

A list of messages sent by the agent and user. Learn more about the Message object.

sendMessage

function

A function to send a message to the agent. It takes the following parameters:

{
  userMessage: string;
  appConfig: any;
  payload?: any;
}

startNewConversation

function

A function to start a new conversation with the agent.

`Message`

The Message object has the following properties:

sender

enum: MessageSender

required

The sender of the message. Can be either user or agent.

message

string

The content of the message.

data

json

Additional data associated with the message.

toolCallResults

ToolCallResult[]

[User-Only] For client-side tool execution, the results of the tool call

appConfig

json

[User-Only] App config value for your Agent. Learn more about App Config.

requestId

string

[Agent-Only] Request ID associated with the message.

intermediateSteps

IntermediateStep[]

[Agent-Only] Intermediate steps that the agent has taken. This can be used for debugging or logging purposes, or to provide additional context to the client. IntermediateStep has the following fields:

{
  name: string; // name or description of the intermediate step
  data?: any; // additional data for the intermediate step
}

toolCalls

[Agent-Only] For client-side tool execution, the tool calls to be executed

@palico-ai / client-js

@palico-ai / react

REST API

Setup and Installation

Usage

Client-Side Tool Execution

API reference

`useChat()`

`Message`

​Setup and Installation

​Usage

​Client-Side Tool Execution

​API reference

​useChat()

​Message

Setup and Installation

Usage

Client-Side Tool Execution

API reference

`useChat()`

`Message`