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.
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.  EachOnly session is immutablethe acess level can be changed on an existing session.  You will need to start a new session if you wish to use a different access level or 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"
		},
		"agentIdagentRegistrationId": {
			"type": "string",
			"description": "Optional. Most users When provided, the registered agent will notbe used usefor this parametersession.  IfWhen youexcluded arethe authorizeddefault to'baseline' testagent experimentalwill agents, provide the ID of the agent you wish to test."
	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."
		}
	]
}

...

Code Block

language	json

{
	"description": "Information about a specific session (conversation) with an agent.  Only the acess  Each session is immutablelevel can be changed on an existing session.  You will need to start a new session if you wish to use a different access level or 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."
		},
		"agentIdstartedBy": {
			"type": "stringinteger",
			"description": "IdentifiesThe thatid agentof thatthe willuser bethat usedstarted for this session.  The default value is null, which indicates that the default agent will be used"
		},
		"modifiedOn": {
			"type": "string",
			"format": "date-time",
			"description": "The date this session was last modified."
		},
	}
}

ListAgentSessionsRequest:

Code Block

language	json

{
	"agentRegistrationId": {
			"type": "string",
			"description": "RequestIdentifies that aagent singlethat pagewill agentbe sessionsused for thethis current usersession.  The sessiondefault arevalue orderedis by 'startedOn' descending.",
	"properties": {
		"nextPageTokennull, which indicates that the default agent will be used."
		},
		"etag": {
			"type": "string",
			"description": "ForwardWill the returned 'nextPageToken' to get the next page of resultschange whenever the session changes."
		}
	}
}

ListAgentSessionsResponseListAgentSessionsRequest:

Code Block

language	json

{
	"description": "ARequest a single page of agent sessions",
	"properties": {
		"page": {
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.agent.AgentSession"
			}
		},
		 for the current user.  The session are ordered by 'startedOn' descending.",
	"properties": {
		"nextPageToken": {
			"type": "string",
			"description": "Forward this tokenthe returned 'nextPageToken' to get the next page of results."
		}
	}
}

AgentChatRequestListAgentSessionsResponse:

Code Block

language	json

{
	"description": "SendA asingle chatpage messageof toagent the Synapse chat agent",
	"implements": [
		{
sessions",
	"properties": {
		"page": {
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.asynchagent.AsynchronousRequestBodyAgentSession"
			}
	]	},
		"propertiesnextPageToken": {
			"sessionIdtype": {"string",
			"description": "TheForward sessionIdthis thattoken identifiesto get the conversationnext withpage theof agentresults.",
			"type": "string"}
		},
		"chatText": 
}

AgentChatRequest:

Code Block

language	json

{
			"description": "TheSend user'sa textchat message to sendthe toSynapse thechat agent.",
			"typeimplements": "string"[
		},{
			"enableTrace$ref": {"org.sagebionetworks.repo.model.asynch.AsynchronousRequestBody"
		}
	],
	"descriptionproperties": "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.",{
		"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": "The 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": {
			"type": "string",
			"description": "Forward the returned 'nextPageToken' to get the next page of results."
		}
	}
}

SessionHistoryResponse:

Code Block

language	json

{
	"description": "A single page of an agent session history",
	"properties": {
		"sessionId": {
			"description": "The session ID of this conversation'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": "Forward this token to get the next page of results."
		}
	}
}

Interaction:

Code Block

language	json

{
	"description": "Represents a single interaction between the user and an agent.",
	"properties": {
		"usersRequestText": {
			"type": "string",
			"description": "The text of the user's request"
		},
		"usersRequestTimestamp": {
			"type": "booleanstring",
		}
	}
}

AgentChatResponse:

Code Block

language	json

{
		"format": "date-time",
			"description": "The responsetime tostamp an agent chat request.",
	"implements": [
		{
			"$ref": "org.sagebionetworks.repo.model.asynch.AsynchronousResponseBodywhen the user made the request"
		},
	],
	"propertiesagentResponseText": {
			"sessionIdtype": {"string",
			"description": "The sessionIdtext that identifiesof the conversation with the agent.",agent's response"
		},
		"agentResponseTimestamp": {
			"type": "string"
		}",
			"responseTextformat": {"date-time",
			"description": "The agent'stime textstamp responsewhen to the user's request",
			"type": "string"agent produced the response."
		}
	}
}

SessionHistoryRequestTraceEventsRequest:

Code Block

language	json

 {
	"description": "RequestA request to get a single page of a session's history.  The history is ordered by the interaction time stamp descendingtrace events for a specified asynchronous job.",
	"properties": {
		"nextPageTokenjobId": {
			"type": "string",
			"description": "ForwardThe thejob returnedID 'nextPageToken' to get the next page of results."
		}
	}
}

SessionHistoryResponse:

Code Block

language	json

{
	"description": "A single page of an agent session history",
	"propertiesissued when the agent chat request job was started."
		},
		"newerThanTimestamp": {
			"sessionIdtype": {"integer",
			"description": "The session ID of this conversation's history",
			"type": "stringWhen a timestamp value is provided, only trace events that occurred after the provided timestamp will be included in the results."
		},
		"page": {
			}
}

TraceEventsResponse

Code Block

language	json

{
	"description": "A single page of a session's history.  The history is ordered by the interaction time stamp descending.",
			"type": "array",
			"itemsan agent trace events for an asynchronous agent chat job. The events are sorted by timestamp ascending.",
	"properties": {
				"$ref": "org.sagebionetworks.repo.model.agent.Interaction"
			}
		},
		"nextPageToken"jobId": {
			"type": "string",
			"description": "ForwardThe thisjob tokenID toissued getwhen the agent nextchat request pagejob ofwas resultsstarted."
		},
	}
}

Interaction:

Code Block

language	json

	"page": {
			"description": "Represents aA single interactionpage betweenof the user and an agent.",
	"properties": {
		"usersRequestText": {
			"type": "string",
		trace events.",
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.agent.TraceEvent"
			}
		}
	}
}

TraceEvent:

Code Block

language	json

{
	"description": "The text of the user's request"
		},
		"usersRequestTimestampRepresents a single trace event generated during an agent chat asynchronous job request.",
	"properties": {
			"typetimestamp": "string",{
			"formattype": "date-timeinteger",
			"description": "The time stamp identifies when the user made the request"
		},
		"agentResponseText": {
			"type": "string",
			"description": "The text of the agent's response agent generated this trace event.  It is also used to uniquely identify this event within the context of this asynchronous job."
		},
		"agentResponseTimestampmessage": {
			"type": "string",
			"formatdescription": "date-time",
			"description": "The time stamp whenThe trace text message generated by the agent produced the responsewhile processing a chat request."
		}
	}
}

TraceEventsRequest:AgentRegistrationRequest.json

Code Block

language	json

{
	"description": "A request to get a single page of trace events for a specified asynchronous jobRequest to register a custom AWS agent with Synapse.  Currently, only internal users are authorized to register custom agents.",
	"properties": {
		"jobIdawsAgentId": {
			"type": "string",
			"description": "The AWS jobissued agent ID issued whenof the agent chatto request job was startedbe registered."
		},
		"newerThanTimestampawsAliasId": {
			"type": "integerstring",
			"description": "When a timestamp value is provided, only trace events that occurred after the provided timestampThe AWS issued agent alias ID of the agent alias to be used. Optional. If an alias is not provided then 'TSTALIASID' will be included in the resultsused."
		}
	}
}

TraceEventsResponse

...

language	json

...

AgentRegistration.json

Code Block

language	json

{
	"description": "The registration of a custom AWS agent.",
	"properties": {
		"jobIdagentRegistrationId": {
			"type": "string",
			"description": "The jobunique ID issued by Synapse when thethis agent chat request job was started."
		},
		"page": {
			"description": "A single page of trace events.",
			"type": "array",
			"itemswas registered. Provide this ID when starting a session to use the registered agent for a session."
		},
		"awsAgentId": {
				"$ref": "org.sagebionetworks.repo.model.agent.TraceEvent"
			}
		}
	}
}

TraceEvent:

Code Block

language	json

{
	type": "string",
			"description": "RepresentsThe aAWS singleissued traceagent eventID generatedof during anthe agent chat asynchronous job request.",
	"properties": {		},
		"timestampawsAliasId": {
			"type": "integerstring",
			"description": "The timeAWS stamp identifies when the issued agent generated this trace event.  It is also used to uniquely identify this event within the context of this asynchronous jobalias ID. If an alias ID was not provided, a default value of 'TSTALIASID' will be used."
		},
		"messageregisteredOn": {
			"type": "string",
			"format": "date-time",
			"description": "The tracedate text message generated by the this agent while processing a chat requestwas registered."
		}
	}
}

Versions Compared

Old Version 8

New Version Current

Key

Object Models