...
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 | ||
|---|---|---|
| ||
{
"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 | ||
|---|---|---|
| ||
{
"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 | ||
|---|---|---|
| ||
{
"description": "A single page of an agent trace events for an asynchronous agent chat job. The events are sorted by timestamp ascending.",
"properties": {
"jobId agent chat job. The events are sorted by timestamp ascending.",
"properties": {
"jobId": {
"type": "string",
"description": "The job ID issued when the agent chat request job was started."
},
"page": {
"description": "A single page of trace events.",
"type": "array",
"items": {
"$ref": "org.sagebionetworks.repo.model.agent.TraceEvent"
}
}
}
} |
TraceEvent:
| Code Block | ||
|---|---|---|
| ||
{
"description": "Represents a single trace event generated during an agent chat asynchronous job request.",
"properties": {
"timestamp": {
"type": "integer",
"description": "The 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": "The trace text message generated by the agent while processing a chat request."
}
}
} |
RegisterAgentRequest.json
| Code Block | ||
|---|---|---|
| ||
{
"description": "Request to register a custom AWS agent with Synapse. Currently, only internal users are authorized to register custom agents.",
"properties": {
"awsAgentId": {
"type": "string",
"description": "The AWS issued agent ID of the agent to be registered."
},
"awsAliasId": {
"type": "string",
"description": "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."
}
}
} |
AgentRegistration.json
| Code Block | ||
|---|---|---|
| ||
{ "description": "The registration of a custom AWS agent.", "properties": { "agentRegistrationId": { "type": "string", "description": "The 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", "description": "The AWS issued agent ID of the agent." }, "awsAliasId": { "type": "string", "description": "The job AWS issued agent alias ID. If an alias ID issued when the agent chat request job was started was not provided, a default value of 'TSTALIASID' will be used." }, "pageregisteredOn": { "descriptiontype": "A single page of trace events.string", "typeformat": "arraydate-time", "itemsdescription": { "$ref": "org.sagebionetworks.repo.model.agent.TraceEvent" }"The date this agent was registered." }, } } |
TraceEvent:
| Code Block | ||
|---|---|---|
| ||
"registeredBy": { "descriptiontype": "Represents a single trace event generated during an agent chat asynchronous job request.", "properties": { "timestampinteger", "description": "The id of the user that created this registration." }, "name": { "type": "integerstring", "description": "The timename stampof identifies when the agent generatedprovided this trace event. It is also used to uniquely identify this event within the context of this asynchronous jobby AWS." }, "messagedescription": { "type": "string", "description": "The tracedescription text message generated by of the agent whileprovided processing a chat requestby AWS." } } } |