Conversation API for Agents
How to create a task/conversation with an Agent
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?