Quickstart

This tutorial assumes you have already followed the Account Setup steps to obtain an api_key and org_id, and have followed the Installation steps to get your developer environment set up correctly and the engagesmarter Python library installed.

Initialising the library

To use the library, you need to import the Engage Smarter Client and initialise it with your api_key and org_id as parameters.

In the following example we assume that you have stored your api_key and org_id in environment variables named ENGAGE_SMARTER_API_KEY and ENGAGE_SMARTER_ORG_ID respectively.

import os

from engagesmarter import Client

api_key = os.getenv("ENGAGE_SMARTER_API_KEY")
org_id = os.getenv("ENGAGE_SMARTER_ORG_ID")

client = Client(
    api_key=api_key,
    org_id=org_id,
)

API Security

You should keep your API key and Org ID stored safely and import them as an environment variables, for instance using os.getenv("ENGAGE_SMARTER_API_KEY").

Never hard-code your API key into your code base, commit it to GitHub, or include it in client-side code. If you are concerned that your key has been comprised, delete it and create a new one.

Starting a first Conversation

Let's now start a first Conversation with an AI agent via the Engage Smarter API. To do this, we need to do two things:

1. Create a new conversation
2. Send a message to the agent in conversation

First we create a new conversation as follows and store the conversation_id for later use:

conversation = client.conversations.create()
conversation_id = conversation.id

Conversations API

In this Quickstart example, we use the Conversations API. We also have a Runs API which does not require creating a Conversation and then interacting. To explore each further, see the tutorials in the Basics section.

Choosing an AI agent

The Engage Smarter AI Platform includes many public and custom AI agents. This will be maintained, updated and added to over time. Agents are identified by their string name. All the agents currently available to you are available in a list using the following.

agents = client.agents.list()

In this example, we will choose to use the pensions-questions-latest agent.

AGENT = "pensions-questions-latest"

Available Agents

To learn more about Agents, see the Agents section.

Sending the first user message

Next we can send a first UserMessage to an agent. The response will be an agent message.

Messages

To enable more advanced use cases, the API accepts a list of messages rather than a single user message. Here we wrap our single user message in a list.

from engagesmarter import UserMessage

user_message = UserMessage(content="Hello, can you help me understand pensions?")

response = client.conversations.chat_with_agent(
    conversation_id=conversation_id,
    messages=[user_message],
    agent=AGENT,
)
agent_message = response[0]

Let's print the content of the agent's message to see what the agent said:

print(agent_message.content)

    Of course, I'm here to help you understand pensions! Pensions can be complex, but I'll do my best to explain. What specifically would you like to know about pensions? Are you interested in how pensions are run, what happens to your pension when you die, or something else? Let me know and I'll provide you with the information you need.

Subsequent messages

Your user can send subsequent messages which will be attached to the same conversation thread. You do not send original messages again. Any messages that have been sent using the Conversation API will be remembered by the system from each step to the next.

Simply call the same function again with the next message as follows.

user_message = UserMessage(
    content="OK, so can I take money from my pension?  I'm aged 53 just now and not working anymore."
)

response = client.conversations.chat_with_agent(
    conversation_id=conversation_id,
    messages=[user_message],
    agent=AGENT,
)
agent_message = response[0]

Summary

You have now successfully sent your first message to an agent and received a response!

You have:

• Set up your User account and API key
• Learned where to find your org_id
• Started your first Conversation in the Engage Smarter API

Next steps

The Engage Smarter AI Platform is organised into different API resources, each covering different areas of functionality. So far we have used the Conversations API resource. To learn more about the different API resources, continue to the next tutorial on viewing available Agents via the Agents resource.

The API offers two different APIs for interacting with agents: Conversations and Runs. To learn about each of these, turn to the Conversations or Runs sections.