This page explains all the required steps to successfully make an API call to your Agent.

​

Relevance Keys

When on API keys page, scroll down and you will see the Region code and your Project Id.

To generate your Relevance API key, click on "Create new secret key", with the role "Admin". Click on "Generate API key". Copy the values shown on the modal.

• Authorization token
• API key
• Region
• Project

​

Agent Id

Currently, the easiest way to access Agent Ids is from URLs. For instance, when on the "Edit agent" page, the last piece after project id and before /edit shows the Agent Id. The URL is structured as

https://app.relevanceai.com/agents/REGION/Project-Id/Agent-Id/edit

​

Studio Id and Job Id

• Step 1: Authorization Token

  Either directly copy the Authorization token from the API page (see above for instructions) or use the Project id and API key combination as shown in the snippet below:

  authorization_token = f"{project_id}:{api_key}"   # Both values can be found in the API Keys page
  
  

• Step 2: Region and Agent id

  Fetch the values as instructed further up in this page

  region = Region       # Can be found in the API Keys page
  agent_id = Agent_id   # Can be found in the Agent page URL
  
  

• Step3: Agent's studio and job ids

  Run the Python snippets below with corresponding values for Region, Authorization token and Agent Id on your project.

  import requests
  import json
  import time
  
  # Define the URL, authorization header, and the JSON payload
  
  url = f"https://api-{region}.stack.tryrelevance.com/latest/agents/trigger"
  headers = {
      "Authorization": authorization_token,
      "Content-Type": "application/json"
  }
  payload = {"message":{"role":"user","content":"Hello"},"agent_id":agent_id}
  
  # Convert the payload to a JSON string
  payload_json = json.dumps(payload)
  
  # Send the POST request
  response = requests.post(url, headers=headers, data=payload_json)
  
  # Check the response
  if response.status_code == 200:
      print("Request was successful!")
      print("Response:", response.text)
  else:
      print("Request failed with status code:", response.status_code)
      print("Response:", response.text)
  
  

  The endpoint to access an Agent's info:

  https://api-{region}.stack.tryrelevance.com/latest/agents/trigger

  <region> can be found at API keys.

  In a successful run, the output is a dictionary containing "studio_id" and "job_id" which are required for the next step (i.e agent_details). We can access the corresponding values via the code below.

  agent_details = response.json()
  

​

Conversation with the Agent

To start a conversation with your Agent, provide the corresponding values for Region and Authorization token in the code snippet below and that’s all :)

authorization_token = f"{project_id}:{api_key}"  # Or copy directly from the API Keys page
region = Region                                  # Can be found in the API Keys page

# Replace these with the actual values obtained from the previous response
studio_id = agent_details["job_info"]["studio_id"]
job_id = agent_details["job_info"]["job_id"]

done = False
message = None

while True:
  # Define the URL with placeholders for studio_id and job_id
  url = f"https://api-{region}.stack.tryrelevance.com/latest/studios/{studio_id}/async_poll/{job_id}"

  # Define the authorization header
  headers = {
      "Authorization": authorization_token
  }

  # Send the POST request
  response = requests.get(url, headers=headers)

  message = response.json()

  for update in message['updates']:
    if update['type'] == "chain-success":
      done = True

  if done == True:
    break

  time.sleep(1000)

​

List messages in a conversation

To list all the messages in a conversation, you can use the following code snippet. The messages will be reverse chronological order, i.e. the newest message will be the first in the list.

# Define the authorization header
headers = {
  "Authorization": authorization_token
}

conversation_id = agent_details["conversation_id"]

# Define the URL with placeholders for studio_id and job_id
url = f"https://api-{region}.stack.tryrelevance.com/latest/knowledge/list"

payload = {
  "knowledge_set": conversation_id,
  "page_size": 20,
  "sort": [
    {
      "insert_date_": "desc"
    }
  ]
}

messages = requests.post(url, headers=headers, json=payload).json()['results']

The messages follow this general structure:

{
  "data": {
    "message": {
      "role": "" // the type of message in the conversation history. e.g. "user", "agent", "action-request"
      // ...other details dependent on the "role" above
    }
  }
}

​

Continue a conversation

To continue a conversation, you’ll need the conversation_id returned when you triggered the agent, e.g. agent_details["conversation_id"] in the Conversation with the agent section above. Then, you can trigger the agent as before, but with the conversation_id provided in the payload.

# ... previous code same as before

payload = {
  "message": {
    "role": "user",
    "content": "Hello"
  },
  "agent_id": agent_id
  "conversation_id": agent_details["conversation_id"]
}

# ... subsequent code same as before

You can then follow the

​

Confirm or reject a tool run

As above, you’ll need the conversation_id returned when you triggered the agent. You’ll also need the action_request_id and action of the tool run that you want to confirm or reject. You can find it using the api request here and it should be the newest (first) message in your conversation.

# ... previous code same as before

action_request_message = message[0]['data']['message']
action = action_request_message['action']
action_request_id = action_request_message['action_request_id']

payload = {
  "message": {
    "role": "action-confirm", # or "action-reject"!
    "action": action,
    "action_request_id": action_request_id
  },
  "agent_id": agent_id
  "conversation_id": agent_details["conversation_id"]
}

# ... previous code same as before