Runs

note

This page assumes you are already familiar with how get hold of an api_key and org_id and how to install the Engage Smarter Python library. If not, turn to the Getting Started tutorial.

Conceptual overview

The Engage Smarter AI Runs API is a secondary API for interacting with agents on the platform.

Unlike the Conversations API, the Runs API is not stateful. This means that it is typically used in the cases where a single response is required from the Agent.

In order to use the Runs API, you need to send the full conversation history of messages required in this one run request.

Under the hood, the Runs API does create a Conversation for this one run and the conversation_id is returned as part of the response message. This allows you the option to switch to the Conversations API for further messages after the initial Run.

note

This stateless API setup for the Runs API is similar in structure to the standard OpenAI API setup which also requires the client to send the full conversation history with every API call.

Pre-requisites

First, we initialise the Engage Smarter Python Client.

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,
)

Creating a run

from engagesmarter import AgentMessage, UserMessage

AGENT = "pensions-questions-latest"

user_message_1 = UserMessage(content="Hello, can you help me understand pensions?")
agent_message_1 = AgentMessage(content="I can yes.  What do you want to know?")
user_message_2 = UserMessage(content="What is a DC pension?")


response = client.runs.chat_with_agent(
    messages=[user_message_1, agent_message_1, user_message_2],
    agent=AGENT,
)

response

    [MessageRead(id='0662787f-f6ab-736f-8000-c2b283e87fba', org_id='065d66dd-e3ce-7969-8000-f2372634456f', conversation_id='0662787f-463b-7ea4-8000-56347003c67d', run_id='0662787f-468a-79e4-8000-2b4ac4126183', role='agent', content='A Defined Contribution (DC) pension is a type of pension where you make contributions that are invested to build up a pot of money for your retirement. The value of your pension pot depends on how much you contribute, how long your contributions are invested, and how your investments perform over time. When you retire, you have various options for using your DC pension, such as taking a tax-free lump sum and using the rest to provide a regular taxable income or taking your pension pot in one go. Does this make sense?', name='pensions-questions-240228-dev', user_id='065d64bc-2480-7b32-8000-bd68db1e258e', created=datetime.datetime(2024, 4, 23, 10, 5, 51, 416000))]

message = response[0]
print(message.model_dump_json(indent=2))

    {
      "id": "0662787f-f6ab-736f-8000-c2b283e87fba",
      "org_id": "065d66dd-e3ce-7969-8000-f2372634456f",
      "conversation_id": "0662787f-463b-7ea4-8000-56347003c67d",
      "run_id": "0662787f-468a-79e4-8000-2b4ac4126183",
      "role": "agent",
      "content": "A Defined Contribution (DC) pension is a type of pension where you make contributions that are invested to build up a pot of money for your retirement. The value of your pension pot depends on how much you contribute, how long your contributions are invested, and how your investments perform over time. When you retire, you have various options for using your DC pension, such as taking a tax-free lump sum and using the rest to provide a regular taxable income or taking your pension pot in one go. Does this make sense?",
      "name": "pensions-questions-240228-dev",
      "user_id": "065d64bc-2480-7b32-8000-bd68db1e258e",
      "created": "2024-04-23T10:05:51.416000"
    }