Page Comparison

...

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:

...

language	json

...

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

language	json

{
	"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

language	json

{
	"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

language	json

{
	"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

language	json

{
	"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

language	json

{
	"description": "A single page of agent sessions",
	"properties": {
		"page": {
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.agent.AgentSession"
			}
		},
		"nextPageToken": {
			"type": "string",
			"description": "Forward this token to get the next page of results."
		}
	}
}

AgentChatRequest:

Code Block

language	json

{
	"description": "Send a chat message to the Synapse chat agent",
	"implements": [
		{
			"$ref": "org.sagebionetworks.repo.model.asynch.AsynchronousRequestBody"
		}
	],
	"properties": {
		"sessionId": {
			"description": "The sessionId that identifies the conversation with the agent.",
			"type": "string"
		},
		"chatText": {
			"description": "The user's text message to send to the agent.",
			"type": "string"
		},
		"enableTrace": {
			"description": "Optional. When trace is enabled, the agent will include information about its decision process and the functions/tools it will use to process this request. Default value is false.",
			"type": "boolean"
		}
	}
}

AgentChatResponse:

Code Block

language	json

{
	"description": "The response to an agent chat request.",
	"implements": [
		{
			"$ref": "org.sagebionetworks.repo.model.asynch.AsynchronousResponseBody"
		}
	],
	"properties": {
		"sessionId": {
			"description": "The sessionId that identifies the conversation with the agent.",
			"type": "string"
		},
		"responseText": {
			"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 agentIdThe agent's text response to the user's request",
			"type": "string"
		}
	}
}

SessionHistoryRequest

Code Block

language	json

 {
	"description": "Request a single page of a session's history.  The history is ordered by the interaction time stamp descending.",
	"properties": {
		"nextPageToken": {
			"agentAccessLeveltype": {"string",
			"description": "Required.Forward Specifiesthe thereturned access'nextPageToken' levelto thatget the agentnext willpage have during this session onlyof results.",
		}
	"$ref}
}

SessionHistoryResponse:

Code Block

language	json

{
	"description": "org.sagebionetworks.repo.model.agent.AgentAccessLevel"
		},
		"agentIdA single page of an agent session history",
	"properties": {
			"typesessionId": "string",{
			"description": "Optional. Most users will not use this parameter.  If you are authorized to test experimental agents, provide the": "The session ID of thethis agent you wish to test.conversation's history",
			"type": "string"
		},
		}
}

AgentAccessLevel:

Code Block

language	json

"page": {
			"description": "DefinesA thesingle levelpage of data access that the agent will be given during a session a session's history.  The history is ordered by the interaction time stamp descending.",
			"nametype": "AgentAccessLevelarray",
			"items": {
				"type$ref": "string"org.sagebionetworks.repo.model.agent.Interaction"
			}
		},
		"enumnextPageToken": [ 		{
			"nametype": "PUBLICLY_ACCESSIBLEstring",
			"description": "TheForward agentthis will only have access token to ALLget datathe thatnext ispage already publicly available to anyone."
		},
		{
			"name": "READ_YOUR_PRIVATE_DATA",of results."
		}
	}
}

Interaction:

Code Block

language	json

{
	"description": "TheRepresents agenta willsingle haveinteraction accessbetween tothe ALLuser dataand 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_DATAan agent.",
	"properties": {
		"usersRequestText": {
			"type": "string",
			"description": "The text of the user's request"
		},
		"usersRequestTimestamp": {
			"type": "string",
			"format": "date-time",
			"description": "GrantThe thetime 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 availablestamp when the user made the request"
		},
		"agentResponseText": {
			"type": "string",
			"description": "The text of the agent's response"
		},
		"agentResponseTimestamp": {
			"type": "string",
			"format": "date-time",
			"description": "The time stamp when the agent produced the response."
		}
	]}
}

AgentSessionTraceEventsRequest:

Code Block

language	json

{
	"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 agentIdA request to get a single page of trace events for a specified asynchronous job.",
	"properties": {
		"sessionIdjobId": {
			"type": "string",
			"description": "The uniquejob identifierID forissued a conversation with anwhen the agent. chat Therequest 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 itjob was started."
		},
		"newerThanTimestamp": {
			"type": "integer",
			"description": "When a timestamp value is provided, only trace events that occurred after the provided timestamp will be included in the results."
		},
		"agentAccessLevel": 
	}
}

TraceEventsResponse

Code Block

language	json

{
			"description": "Specifies the access level that theA single page of an agent trace events for an asynchronous agent willchat havejob. duringThe thisevents session only.",
			"$ref": "org.sagebionetworks.repo.model.agent.AgentAccessLevel"
		},are sorted by timestamp ascending.",
	"properties": {
		"startedOnjobId": {
			"type": "string",
			"formatdescription": "date-time"The job ID issued when the agent chat request job was started."
		},
		"page": {
			"description": "TheA datesingle thispage sessionof wastrace startedevents.",
		},
		"agentIdtype": {"array",
			"typeitems": "string",{
				"description$ref": "Identifies that agent that will be used for this session.  The default value is null, which indicates that the default agent will be used."
		}
	}
}

ListAgentSessionsRequest:

Code Block

language	json

{
org.sagebionetworks.repo.model.agent.TraceEvent"
			}
		}
	}
}

TraceEvent:

Code Block

language	json

{
	"description": "Represents a single trace event generated during an agent chat asynchronous job request.",
	"properties": {
		"timestamp": {
			"type": "integer",
			"description": "Request a single page agent sessions for the current user.  The session are ordered by 'startedOn' 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."
		}
	}
}

ListAgentSessionsResponse:AgentRegistrationRequest.json

Code Block

language	json

{
	"description": "A single page of agent sessions",
	"properties": {
		"page": {
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.agent.AgentSession"
			}
		},
		"nextPageTokenRequest to register a custom AWS agent with Synapse.  Currently, only internal users are authorized to register custom agents.",
	"properties": {
		"awsAgentId": {
			"type": "string",
			"description": "ForwardThe AWS thisissued tokenagent toID getof the nextagent pageto ofbe resultsregistered."
		},
	}
}

AgentChatRequest:

Code Block

language	json

{
		"awsAliasId": {
			"type": "string",
			"description": "SendThe aAWS chatissued messageagent toalias theID Synapseof chatthe agent",
	"implements": [
		{
			"$ref": "org.sagebionetworks.repo.model.asynch.AsynchronousRequestBody alias to be used. Optional. If an alias is not provided then 'TSTALIASID' will be used."
		}
	],
	"properties": {
		"sessionId": }
}

AgentRegistration.json

Code Block

language	json

{
			"description": "The sessionIdregistration thatof identifiesa the conversation with thecustom AWS agent.",",
	"properties": {
			"typeagentRegistrationId": "string"{
		},
		"chatTexttype": {"string",
			"description": "The user's text message to send to the agent.",
			 unique ID issued by Synapse when this agent was registered. Provide this ID when starting a session to use the registered agent for a session."
		},
		"awsAgentId": {
			"type": "string",
		}
	}
}

AgentChatResponse:

Code Block

language	json

{
	"description": "The responseAWS to anissued agent chat request.",
	"implements": [
		{
			"$ref": "org.sagebionetworks.repo.model.asynch.AsynchronousResponseBodyID of the agent."
		},
	],
	"propertiesawsAliasId": {
			"sessionIdtype": {"string",
			"description": "The sessionId that identifies the conversation with the agent.",
		 AWS issued agent alias ID. If an alias ID was not provided, a default value of 'TSTALIASID' will be used."
		},
		"registeredOn": {
			"type": "string",
		},
		"responseTextformat": {"date-time",
			"description": "The agent'sdate textthis responseagent to the user's request",
			"type": "stringwas registered."
		}
	}
}

Versions Compared

Old Version 3

New Version Current

Key

Object Models

Object Models