Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Response

url

Request

Description

Authorization

AgentSession

POST /agent/session

CreateAgentSessionRequest

Used to start a new session with the Synapse agent.

A user must be authenticated to make this call.

ListAgentSessionsResponse

POST /agent/sessions/list

ListAgentSessionsRequest

List all of the user’s sessions starting with the latest.

Will only list sessions that belong to the caller.

SessionHistoryResponse

POST /agent/session/history/{sessionId}

SessionHistoryRequest

Get a single page of a session’s conversation history.

Only the owner of the session may make this call.

JobState

POST /agent/chat/async/start

AgentChatRequest Start

Start an asynchronous job to send a chat message to the Synapse agent.

A user must be authenticated to make this call. The provided sessionId must belong to the caller. The agent’s access level will be determined by the level selected by the users for the session.

AgentChatResponse

GET /agent/chat/async/get/{job_id}

Get the results of an asynchronous job that contains the Synapse agent’s response to a user’s request.

Authentication required. Only the user that started the job can get its results.

Object Models

CreateAgentSessionRequest:

...

languagejson

...

TraceEventsResponse

POST /agent/chat/trace/{job_id}

TraceEventsRequest

Get a single page of trace events associated with an AgentChatRequest job. Note: The AgentChatRequest.enableTrace must be set to “true” to enable tracing for a job.

Authentication required. Only the user that started the job can get its results.

AgentRegistration

PUT /agent/registration

RegisterAgentRequest

Idempotent registration of a custom agent.

Only internal users (Sage employees) will be authorized to register agents.

AgentRegistration

GET /agent/registration/{agentRegistrationId}

Get the details of registered custom agent using its ID.

A user must be authenticated to make this call.

Object Models

CreateAgentSessionRequest:

Code Block
languagejson
{
	"description": "Information about a specific session (conversation) with an agent.  Only the acess level can be changed on an existing session.  You will need to start a new session if you wish to use a different agentId.",
	"properties": {
		"agentAccessLevel": {
			"description": "Required. Specifies the access level that the agent will have during this session only.",
			"$ref": "org.sagebionetworks.repo.model.agent.AgentAccessLevel"
		},
		"agentRegistrationId": {
			"type": "string",
			"description": "Optional. When provided, the registered agent will be used for this session.  When excluded the default 'baseline' agent will be used."
		}
	}
}

AgentAccessLevel:

Code Block
languagejson
{
	"description": "Defines the level of data access that the agent will be given during a session.",
	"name": "AgentAccessLevel",
	"type": "string",
	"enum": [
		{
			"name": "PUBLICLY_ACCESSIBLE",
			"description": "The agent will only have access to ALL data that is already publicly available to anyone."
		},
		{
			"name": "READ_YOUR_PRIVATE_DATA",
			"description": "The agent will have access to ALL data in Synapse that you have 'read' access to.  The agent will also have access to ALL data that is publicly available."
		},
		{
			"name": "WRITE_YOUR_PRIVATE_DATA",
			"description": "Grant the agent permission to make data changes within Synapse on your behalf. Any change the agent makes will be attributed to you.  Under this level the Agent will also have access to ALL data in Synapse that you have 'read' access to.  The agent will also have access to ALL data that is publicly available."
		}
	]
}

AgentSession:

Code Block
languagejson
{
	"description": "Information about a specific session (conversation) with an agent.  Only the acess level can be changed on an existing session.  You will need to start a new session if you wish to use a different agentId.",
	"properties": {
		"sessionId": {
			"type": "string",
			"description": "The unique identifier for a conversation with an agent.  The sessionId issued by Synapse when the session is started.  The caller must provided this sessionId with each chat request to identify a specific conversation with an agent.  A sessionId can only be used by the user that created it."
		},
		"agentAccessLevel": {
			"description": "Specifies the access level that the agent will have during this session only.",
			"$ref": "org.sagebionetworks.repo.model.agent.AgentAccessLevel"
		},
		"startedOn": {
			"type": "string",
			"format": "date-time",
			"description": "The date this session was started."
		},
		"startedBy": {
			"type": "integer",
			"description": "The id of the user that started this session"
		},
		"modifiedOn": {
			"type": "string",
			"format": "date-time",
			"description": "The date this session was last modified."
		},
		"agentRegistrationId": {
			"type": "string",
			"description": "Identifies that agent that will be used for this session.  The default value is null, which indicates that the default agent will be used."
		},
		"etag": {
			"type": "string",
			"description": "Will change whenever the session changes."
		}
	}
}

ListAgentSessionsRequest:

Code Block
languagejson
{
	"description": "Request a single page agent sessions for the current user.  The session are ordered by 'startedOn' descending.",
	"properties": {
		"nextPageToken": {
			"type": "string",
			"description": "Forward the returned 'nextPageToken' to get the next page of results."
		}
	}
}

ListAgentSessionsResponse:

Code Block
languagejson
{
	"description": "A single page of agent sessions",
	"properties": {
		"page": {
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.agent.AgentSession"
			}
		},
		"nextPageToken": {
			"type": "string",
			"description": "InformationForward aboutthis atoken specificto sessionget (conversation)the withnext anpage agent.  Each session is immutable.  You will need to start a new session if you wish to use a different access level or agentId."of results."
		}
	}
}

AgentChatRequest:

Code Block
languagejson
{
	"description": "Send a chat message to the Synapse chat agent",
	"implements": [
		{
			"$ref": "org.sagebionetworks.repo.model.asynch.AsynchronousRequestBody"
		}
	],
	"properties": {
		"agentAccessLevelsessionId": {
			"description": "Required. Specifies the access level "The sessionId that identifies the agentconversation willwith have during this session onlythe agent.",
			"$reftype": "org.sagebionetworks.repo.model.agent.AgentAccessLevelstring"
		},
		"agentIdchatText": {
			"description": "The user's text message to send to the agent.",
			"type": "string"
		},
		"enableTrace": {
			"description": "Optional. Most usersWhen trace is enabled, the agent will notinclude useinformation thisabout parameter.its decision Ifprocess youand arethe authorizedfunctions/tools toit testwill experimentaluse agents,to provideprocess thethis IDrequest. ofDefault the agentvalue you wish to test.is false.",
			"type": "boolean"
		}
	}
}

AgentAccessLevelAgentChatResponse:

Code Block
languagejson
{
	"description": "DefinesThe theresponse level of data access that the agent will be given during a session.",
	"name": "AgentAccessLevel",
	"type": "string"to an agent chat request.",
	"enumimplements": [
		{
			"name$ref": "PUBLICLY_ACCESSIBLE",org.sagebionetworks.repo.model.asynch.AsynchronousResponseBody"
		}
	],
	"description": "The agent will only have access to ALL data that is already publicly available to anyone."
		},
		properties": {
			"namesessionId": "READ_YOUR_PRIVATE_DATA",{
			"description": "The agent will have access to ALL data in Synapse that you have 'read' access to.  The agent will also have access to ALL data that is publicly available."
		},
		{
			"name": "WRITE_YOUR_PRIVATE_DATA",sessionId that identifies the conversation with the agent.",
			"type": "string"
		},
		"responseText": {
			"description": "GrantThe theagent's agenttext permissionresponse to makethe data changes within Synapse on your behalf. Any change the agent makes will be attributed to you.  Under this level the Agent will also have access to ALL data in Synapse that you have 'read' access to.  The agent will also have access to ALL data that is publicly availableuser's request",
			"type": "string"
		}
	}
}

SessionHistoryRequest

Code Block
languagejson
 {
	"description": "Request a single page of a session's history.  The history is ordered by the interaction time stamp descending.",
	"properties": {
		"nextPageToken": {
			"type": "string",
			"description": "Forward the returned 'nextPageToken' to get the next page of results."
		}
	]}
}

AgentSessionSessionHistoryResponse:

Code Block
languagejson
{
	"description": "Information about a specific session (conversation) with an agent.  Each session is immutable.  You will need to start a new session if you wish to use a different access level or agentId.A single page of an agent session history",
	"properties": {
		"sessionId": {
			"type": "string",
			"description": "The uniquesession identifierID forof athis conversation with an agent.  The sessionId issued by Synapse when the session is started.  The caller must provided this sessionId with each chat request to identify a specific conversation with an agent.  A sessionId can only be used by the user that created it."
		},
		"agentAccessLevel": {'s history",
			"type": "string"
		},
		"page": {
			"description": "A single page of a session's history.  The history is ordered by the interaction time stamp descending.",
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.agent.Interaction"
			}
		},
		"nextPageToken": {
			"type": "string",
			"description": "SpecifiesForward thethis accesstoken levelto thatget the agentnext willpage have during this session onlyof results.",
		}
	"$ref}
}

Interaction:

Code Block
languagejson
{
	"description": "org.sagebionetworks.repo.model.agent.AgentAccessLevel"
		}Represents a single interaction between the user and an agent.",
		"startedOnproperties": {
			"typeusersRequestText": "string",{
			"formattype": "date-timestring",
			"description": "The datetext thisof sessionthe was started.user's request"
		},
		"agentIdusersRequestTimestamp": {
			"type": "string",
			"descriptionformat": "Identifies that agent that will be used for this session.  The default value is null, which indicates that the default agent will be used."date-time",
			"description": "The time stamp when the user made the request"
		},
	}
}

ListAgentSessionsRequest:

Code Block
languagejson
{
	"agentResponseText": {
			"type": "string",
			"description": "RequestThe atext singleof pagethe agent sessions for the current user.  The session are ordered by 'startedOn' descending.",
	"properties's response"
		},
		"agentResponseTimestamp": {
			"nextPageTokentype": {"string",
			"typeformat": "stringdate-time",
			"description": "ForwardThe the returned 'nextPageToken' to gettime stamp when the nextagent pageproduced ofthe resultsresponse."
		}
	}
}

ListAgentSessionsResponseTraceEventsRequest:

Code Block
languagejson
{
	"description": "A request to get a single page of agent sessionstrace events for a specified asynchronous job.",
	"properties": {
		"pagejobId": {
			"type": "arraystring",
			"itemsdescription": {
				"$ref": "org.sagebionetworks.repo.model.agent.AgentSession"The job ID issued when the agent chat request job was started."
			}
		},
		"nextPageTokennewerThanTimestamp": {
			"type": "stringinteger",
			"description": "ForwardWhen thisa tokentimestamp tovalue getis the next page of results."
		}
	}
}

AgentChatRequest:

Code Block
languagejson
{
	"description": "Send a chat message to the Synapse chat agent",
	"implements": [
		{
			"$ref": "org.sagebionetworks.repo.model.asynch.AsynchronousRequestBodyprovided, only trace events that occurred after the provided timestamp will be included in the results."
		}
	],
	"properties": {
		"sessionId": }
}

TraceEventsResponse

Code Block
languagejson
{
			"description": "The sessionId that identifies the conversation with the agent.",
			"type": "string"
		},
		"chatTextA single page of an agent trace events for an asynchronous agent chat job. The events are sorted by timestamp ascending.",
	"properties": {
			"descriptionjobId": "The user's text message to send to the agent.",
{
			"type": "string",
		}
	}
}

AgentChatResponse:

Code Block
languagejson
{
	"description": "The job ID responseissued towhen anthe agent chat request job was started."
		},
		"implementspage": [
		{
			"$refdescription": "org.sagebionetworks.repo.model.asynch.AsynchronousResponseBody"A single page of trace events.",
		}
	],
	"propertiestype": {
		"sessionIdarray": {,
			"descriptionitems": "The sessionId that identifies the conversation with the agent.", {
				"type$ref": "stringorg.sagebionetworks.repo.model.agent.TraceEvent"
			},
		"responseText": }
	}
}

TraceEvent:

Code Block
languagejson
{
			"description": "The agent's text response to the user's request",
			Represents a single trace event generated during an agent chat asynchronous job request.",
	"properties": {
		"timestamp": {
			"type": "stringinteger",
		}
	}
}

SessionHistoryRequest

Code Block
languagejson
 {
	"description": "Request a single page of a session's history.  The history is ordered by the interaction time stamp descending.",
	"properties": {
		"nextPageTokenThe time stamp identifies when the agent generated this trace event.  It is also used to uniquely identify this event within the context of this asynchronous job."
		},
		"message": {
			"type": "string",
			"description": "ForwardThe thetrace returnedtext 'nextPageToken'message togenerated getby the agent nextwhile processing pagea ofchat resultsrequest."
		}
	}
}

SessionHistoryResponse:AgentRegistrationRequest.json

Code Block
languagejson
{
	"description": "ARequest to singleregister pagea ofcustom anAWS agent session history",
	"properties": {
		"sessionId": {
			"description": "The session ID of this conversation's history",
			"type": "string"
		},
		"page": {with Synapse.  Currently, only internal users are authorized to register custom agents.",
	"properties": {
		"awsAgentId": {
			"type": "string",
			"description": "AThe singleAWS pageissued ofagent aID session's history.  The history is ordered by the interaction time stamp descending.",of the agent to be registered."
		},
		"awsAliasId": {
			"type": "arraystring",
			"itemsdescription": {
				"$ref": "org.sagebionetworks.repo.model.agent.Interaction "The AWS issued agent alias ID of the agent alias to be used. Optional. If an alias is not provided then 'TSTALIASID' will be used."
			}
		},
		"nextPageToken": {
			"type": "string",
			"
}

AgentRegistration.json

Code Block
languagejson
{
	"description": "ForwardThe thisregistration tokenof toa getcustom the next page of results."
		}
	}
}

Interaction:

Code Block
languagejson
{
AWS agent.",
	"properties": {
		"agentRegistrationId": {
			"type": "string",
			"description": "RepresentsThe unique aID singleissued interactionby betweenSynapse thewhen userthis andagent anwas agentregistered.",
	"properties": {
		"usersRequestText": {
			"type": "string",
			"description": "The text of the user's request Provide this ID when starting a session to use the registered agent for a session."
		},
		"usersRequestTimestampawsAgentId": {
			"type": "string",
			"format": "date-time",
			"description": "The timeAWS stampissued whenagent the userID madeof the requestagent."
		},
		"agentResponseTextawsAliasId": {
			"type": "string",
			"description": "The text AWS issued agent alias ID. If an alias ID was not provided, a default value of the agent's response'TSTALIASID' will be used."
		},
		"agentResponseTimestampregisteredOn": {
			"type": "string",
			"format": "date-time",
			"description": "The timedate stamp whenthis the agent producedwas the responseregistered."
		}
	}
}