​
API authorization set up

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

Authorization tokens are formed by combining Project Id:API Key.

Either directly copy the Authorization token from the API page or use the Project id and API key combination as shown in the snippet below:

project_id = "YOUR_PROJECT_ID" # Can be found in the API Keys page
authorization_token = f"{YOUR_PROJECT_ID}:{YOUR_API_KEY}"   # Both values can be found in the API Keys page
region = "YOUR_REGION"       # Can be found in the API Keys page
base_url = f"https://api-{region}.stack.tryrelevance.com/latest"
headers = {
  "Authorization": authorization_token,
}

​
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

agent_id = "YOUR_AGENT_ID"

​
Trigger an agent / Start a conversation

Agents are async and poll based so to interact with it you’ll need to trigger a job to converse with an agent then continuously poll for updaes.

import requests

trigger_response = requests.post(
  url + "/agents/trigger", 
  headers=headers, 
  json={
    "message":{
      "role":"user",
      "content":"Hello"
    },
    "agent_id":agent_id
  }
)

job = trigger_response.json()

​
Poll the job for updates and replies from the agent.

This will poll the job every 3 minutes for updates.

import time
studio_id = job["job_info"]["studio_id"]
job_id = job["job_info"]["job_id"]

done = False
status = None

while not done:
  response = requests.get(
    base_url + f"/studios/{studio_id}/async_poll/{job_id}", 
    headers=headers
  )

  status = response.json()

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

  if done:
    break

  time.sleep(3)
status

​
Continue the conversation

To continue the conversation just call the trigger endpoint again with the conversation_id. This conversation id can also be found in the url on the agents page https://app.relevanceai.com/agents/{region}/{project_id}/{agent_id}/{conversation_id}.

conversation_id = job["job_info"]["conversation_id"]

reply_response = requests.post(
  base_url + "agents/trigger", 
  headers=headers, 
  json={
    "message": {
      "role": "user",
      "content": "Hello again"
    },
    "agent_id": agent_id,
    "conversation_id": conversation_id
  }
)
reply_response.json()

​
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.

messages = requests.post(base_url + "knowledge/list", headers=headers, json={
  "knowledge_set": conversation_id,
  "page_size": 20,
  "sort": [
    {
      "insert_date_": "desc"
    }
  ]
}).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
    }
  }
}

​
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.


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

reply_response = requests.post(
  base_url + "agents/trigger", 
  headers=headers, 
  json={
    "message": {
      "role": "action-confirm", # or "action-reject"!
      "action": action,
      "action_request_id": action_request_id
    },
    "agent_id": agent_id
    "conversation_id": conversation_id
  }
)
reply_response.json()

Was this page helpful?

Bosh the BDR AgentList conversations