Creating your first agent locally

This guide will show you how to create your first agent which we will test using the web UI provided by us. After this section, you can further enable other communication channels mentioned here.

​

1) Creating your agent on our dashboard

To start, you need to create an account. Head over to the sign up page.

Once you have signed up, click on the create an agent button. Add a name to the agent an an optional description. The name and description is only used for you to identify the agent on our dashboard, and will not be shown to the end user. Let’s create an agent called “TestAgent” with no description.

On the agent screen, you will see the following details:

• The agent name
• The agent description
• URL: You need to modify this value to point to your agent’s webhook (see below).
• Agent API Key: This is the key that is used to communicate to your agent webhook, and for your agent to communicate with AgentReach.
• Client API Key: This is used for clients (for example an SMS integration client) to communicate with AgentReach. You only need this when building a custom client.
• A list of communication channels to manage. See the “Communication channels” section for more details.
• A session view:
  • You can create a new web session by clicking on the “Create new session” button. This will open a chat interface using which you can talk to your agent. Use this for testing your agent.
  • You can view all sessions and conversations of your agent, along with the communication channel used for it.
  • The columns in the table mean:
    • ID: This is a unique identifier for the session.
    • Channel: This is the communication channel used for the session. For example, slack will have slack here, or if you use the “Create new session” button, it will have web-ui here.
    • End user: This is a unique identifier for the end user that initiated the session. At the moment, we do not support automatically authenticating the end user, so this value will be empty.
    • Status: One of “active”, or “completed”. Active means the session is on going, and completed means the session has ended. The semantics of a session that is active vs ended is defined by your agent logic (see below).
    • Created at: This is the timestamp when the session was created.

​

2) Create your agent webhook

You can use any language / framework to create your agent webhook. We are going to use Node.JS with Typescript for this guide. We start by creating a simple express server:

import express from "express";

const app = express();

app.use(express.json());

app.listen(3000, () => {
    console.log("Test agent is listening on port 3000");
});

Next, we add an API endpoint to handle incoming messages from AgentReach.

import express from "express";

const app = express();

app.use(express.json());

app.post("/start-new-session", async (req, res) => {
    let body = req.body;
    if (body.version !== 1) {
        res.status(400).json({ error: "Unsupported version" });
        return;
    }
    res.status(200).json({ success: true });
});

app.listen(3000, () => {
    console.log("Test agent is listening on port 3000");
});

The request body has the following structure:

{
    version: number,
    sessionId: string,
    endUserId: string | undefined,
    message: string,
    channel: {
        type: string,
        email?: string,
        slackUserId?: string
    }
}

• version: This is to identify the version of the request payload. Currently, this is always 1, but you should check it anyway to ensure your agent doesn’t break when there are changes to the payload we send. When we do have multiple versions, and if you send back a 400 status code from your webhook, we will retry with an older enabled version.
• sessionId: This is the session ID that AgentReach will use to identify the session. You can use this string to query our API to manage this session, or talk to the user.
• endUserId: This is the user ID identifying the end user who started the session. If this is not known, this field will not be present in the input JSON.
• message: This is the raw message string sent by the end user to your agent.
• channel: This is an object containing the type of the communication channel, and the relevant user ID or email for that channel.

The webhook above doesn’t really do anything except for responding with a 200 status code. We will see how to add your agent logic in the next step, but for now, we will add this webhook URL to the AgentReach dashboard.

Since we are in a local environment, we need a way for our servers to reach your webhook, which is running on http://localhost:3000. We will use ngrok to create a public URL for our local server. Start by installing ngrok and running the following command:

ngrok http 3000

This will create a public URL (called Forwarding) for your local server. Copy this URL and paste it into the “URL” field in the AgentReach dashboard. For example, if the ngrok url is https://d682-125-99-34-82.ngrok-free.app, you should paste https://d682-125-99-34-82.ngrok-free.app/start-new-session into the “URL” field in the AgentReach dashboard.

Once this is done, you can click on the “Create new session” button in the AgentReach dashboard, and send a message. You should see that your webhook is called and that the req.body object contains the message sent by you.

​

3) Adding auth to your webhook

An important part of securing your webhook is to make sure that it accepts requests only from AgentReach and not just any random bot / client. To do this, we need to add logic to check that the request’s authorization header is valid:

const API_KEY = "<Agent API Key>"

app.post("/start-new-session", async (req, res) => {
    let body = req.body;
    let apiKey = req.headers.authorization?.split(" ")[1];
    if (apiKey !== API_KEY) {
        res.status(401).json({ error: "Unauthorized" });
        return;
    }
    res.status(200).json({ success: true });
});

The “Agent API Key” is shown on the Agent view on the dashboard. This is a secret, so make sure to add it as part of your env file and not hardcode it into your code.

​

4) Messaging users from your agent

As a part of your agent workflow, you may want to message the user in two ways:

• Output something to the user without any response.
• Output something to the user and wait for their response.

We provide APIs for both of these forms of interactions. The APIs take the sessionId along with a message. Here are simple helper functions to use our APIs:

const API_KEY = "<Agent API Key>"

async function showOutputToHuman(sessionId: string, message: string) {
    try {
        let response = await axios.post("https://api.agentreach.ai/v1/session/agent/send-message-to-human", {
            sessionId,
            message,
        }, {
            headers: {
                Authorization: `Bearer ${API_KEY}`,
            }
        });
        if (response.data.shouldRetry) {
            return await sendMessageToHuman(sessionId, message);
        }
    } catch (err) {
        // we retry after sometime
        await new Promise(resolve => setTimeout(resolve, 1000));
        return await sendMessageToHuman(sessionId, message);
    }
}

async function messageHumanAndGetResponse(sessionId: string, message: string): Promise<string> {
    try {
        let response = await axios.post("https://api.agentreach.ai/v1/session/agent/message-human-and-get-response", {
            sessionId,
            message,
        }, {
            headers: {
                Authorization: `Bearer ${API_KEY}`,
            }
        });
        if (response.data.shouldRetry) {
            return await messageHumanAndGetResponse(sessionId, message);
        }
        return response.data.message;
    } catch (err) {
        // we retry after sometime
        await new Promise(resolve => setTimeout(resolve, 1000));
        return await messageHumanAndGetResponse(sessionId, message);
    }
}

More details about these APIs can be found in the showing output to human and the asking for human input sections.

We can use these functions to build our agent workflow as follows:

const API_KEY = "<Agent API Key>"

app.post("/start-new-session", async (req, res) => {
    let sessionId = req.body.sessionId;
    let message = req.body.message;
    let apiKey = req.headers.authorization?.split(" ")[1];
    if (apiKey !== API_KEY) {
        res.status(401).json({ error: "Unauthorized" });
        return;
    }
    await startNewWorkflow(sessionId, message);
    res.status(200).json({ success: true });
});

async function startNewWorkflow(sessionId: string, message: string) {
    if (message.includes("hello")) {
        await showOutputToHuman(sessionId, "Hello there!!");
        return;
    } else {
        let response = await messageHumanAndGetResponse(sessionId, "I am a hello world bot. Type \"hello\" and see what happens!");
        return await startNewWorkflow(sessionId, message);
    }
}

​

5) Ending a session

Once a session has started, it shows as “Active” on the agent dashboard. This means that any new human input will have that session ID as long as their message is in the same “thread” (some communication channels don’t have a multi-thread UI, so users will only be able to interact with one session at a time there).

You can close the session if you like, and this would mark the session as “Completed” on the dashboard. This also means that any new message by the human in that “thread” will be ignored and won’t invoke your webhook.

You can close a session by calling the following API with the sessionId:

const API_KEY = "<Agent API Key>"

await axios.post("https://api.agentreach.ai/v1/session/agent/complete-session", {
    sessionId,
}, {
    headers: {
        Authorization: `Bearer ${API_KEY}`,
    }
});

In the context of the above Hello world bot, you can call this after the startNewWorkflow function has returned.

​

6) Test your agent

You can test your agent easily by using the “Create new session” button on the AgentReach dashboard. Once you click on that, you will see a chat interface using which you can message the agent.

The input box is restricted to only allow messages when the agent is actively waiting for a user input. This behaviour is unique to the web UI we give you, and most other communication channels will just allow you to send messages regardless. In this case, the messages sent by the user will be ignored.

​

7) Next steps

As for next steps, you may read up more on how a session works in the session lifecycle section, and also enable more communication channels for your agent.

If you have any questions, please feel free to click on the Support button on the nav bar above to reach out to us.