openapi: 3.1.0 info: title: Amigo Account Conversation API version: 0.1.0 servers: - url: https://api.amigo.ai - url: https://internal-api.amigo.ai - url: https://api-eu-central-1.amigo.ai - url: https://api-ap-southeast-2.amigo.ai - url: https://api-ca-central-1.amigo.ai security: - Bearer-Authorization: [] Bearer-Authorization-Organization: [] Basic: [] tags: - name: Conversation paths: /v1/{organization}/conversation/: post: tags: - Conversation summary: Create a conversation description: 'Create a new conversation and start it. The user must not have any unfinished conversations that belong to the same service. #### Permissions This endpoint requires the following permissions: * `Conversation:CreateConversation` for the new conversation. This endpoint may be impacted by the following permissions: * `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.' operationId: create-conversation parameters: - name: organization in: path required: true schema: type: string title: Organization - name: response_format in: query required: true schema: enum: - text - voice type: string description: The format of the response that will be sent to the user. title: Response Format description: The format of the response that will be sent to the user. - name: current_agent_action_type in: query required: false schema: type: string description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`. default: ^.*$ title: Current Agent Action Type description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`. - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__create_conversation__Request' responses: '201': description: ' Succeeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available, so the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection. ' content: application/x-ndjson: schema: type: object $ref: '#/components/schemas/src__app__endpoints__conversation__create_conversation__Response' '422': description: Invalid request path parameter or request body failed validation. '404': description: Specified organization, service, or version set is not found. '400': description: ' This may occur for the following reasons: * Attempting to start a conversation when other unfinished conversations exist. * The preferred language does not support voice response. * The `response_audio_format` field is not set when voice output is requested. * The agent does not have voice config specified.' '409': description: A related operation is in progress. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 5 requests per minute for this endpoint. get: tags: - Conversation summary: Get conversations description: 'Retrieve conversations in an organization based on supplied filters. #### Permissions This endpoint may be impacted by the following permissions: * The `final_message` field in the response is only non-empty if the authenticated user has the `Conversation.GetMessage` permission on the final message. * The `version_set_info` field in the response is only non-empty if the authenticated user has the `Service.GetVersionSet` permission on the version set. * Only conversations for which the user has the `Conversation.GetConversation` permission are returned.' operationId: get-conversations parameters: - name: organization in: path required: true schema: type: string title: Organization - name: user_id in: query required: false schema: type: array uniqueItems: true items: type: string description: The identifier of the user whose conversations to retrieve. default: [] title: User Id description: The identifier of the user whose conversations to retrieve. - name: service_id in: query required: false schema: type: array uniqueItems: true items: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the service whose conversation to retrieve. default: [] title: Service Id description: The identifier of the service whose conversation to retrieve. - name: is_finished in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Whether the conversation is finished. title: Is Finished description: Whether the conversation is finished. - name: id in: query required: false schema: type: array items: type: string pattern: ^[a-f0-9]{24}$ description: The ID of the conversation to retrieve. default: [] title: Id description: The ID of the conversation to retrieve. - name: limit in: query required: false schema: type: integer maximum: 150 exclusiveMinimum: 0 description: The maximum number of conversations to retrieve. default: 150 title: Limit description: The maximum number of conversations to retrieve. - name: continuation_token in: query required: false schema: type: integer description: The continuation token returned from the previous response to retrieve the next set of conversations. default: 0 title: Continuation Token description: The continuation token returned from the previous response to retrieve the next set of conversations. - name: sort_by in: query required: false schema: type: array items: type: string description: The field to sort the conversations by. Supported fields are `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties. default: [] title: Sort By description: The field to sort the conversations by. Supported fields are `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties. - name: tag in: query required: false schema: type: array items: type: string description: The tags of the dynamic behavior sets. Must be specified using the syntax `key:value`, which means to match all sets with the given `key` and `value` pair among its tags. If `value` is `*`, it means the `value` does not matter. If `value` is empty, it matches against when the value is `None`. default: [] title: Tag description: The tags of the dynamic behavior sets. Must be specified using the syntax `key:value`, which means to match all sets with the given `key` and `value` pair among its tags. If `value` is `*`, it means the `value` does not matter. If `value` is empty, it matches against when the value is `None`. - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol responses: '200': description: Succeeded. content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__get_conversations__Response' '422': description: Invalid request path parameter or query parameter failed validation. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 15 requests per minute for this endpoint. /v1/{organization}/conversation/{conversation_id}/messages/: get: tags: - Conversation summary: Get conversation messages description: 'Retrieve messages in a conversation, sorted in the specified order, up to the specified limit. #### Permissions This endpoint is impacted by the following permissions: * Only messages that the authenticated user has `Conversation.GetMessage` permission on will be returned.' operationId: get-conversation-messages parameters: - name: organization in: path required: true schema: type: string title: Organization - name: conversation_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the conversation. title: Conversation Id description: The identifier of the conversation. - name: id in: query required: false schema: type: array uniqueItems: true items: type: string pattern: ^[a-f0-9]{24}$ description: The IDs of the messages to retrieve. default: [] title: Id description: The IDs of the messages to retrieve. - name: message_type in: query required: false schema: type: array uniqueItems: true items: $ref: '#/components/schemas/MessageType' description: The type of messages to retrieve. default: - user-message - agent-message - external-event title: Message Type description: The type of messages to retrieve. - name: interaction_id in: query required: false schema: type: array uniqueItems: true items: type: string pattern: ^[a-f0-9]{24}$ description: The IDs of the interactions to retrieve messages for. default: [] title: Interaction Id description: The IDs of the interactions to retrieve messages for. - name: limit in: query required: false schema: type: integer maximum: 500 exclusiveMinimum: 0 description: The maximum number of messages to return. At most 500 messages can be returned in one request. default: 500 title: Limit description: The maximum number of messages to return. At most 500 messages can be returned in one request. - name: continuation_token in: query required: false schema: type: integer description: The continuation token to use to retrieve the next set of messages. default: 0 title: Continuation Token description: The continuation token to use to retrieve the next set of messages. - name: sort_by in: query required: false schema: type: array items: type: string description: The field to sort the messages by. Supported fields are `interaction_id` and `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties. default: [] title: Sort By description: The field to sort the messages by. Supported fields are `interaction_id` and `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties. - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol responses: '200': description: Succeeded. content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__get_conversation_messages__Response' '422': description: Invalid request path parameter failed validation. '404': description: Specified organization or conversation is not found. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 20 requests per minute for this endpoint. /v1/{organization}/conversation/{conversation_id}/finish/: post: tags: - Conversation summary: Finish a conversation description: 'Conclude a conversation and asynchronously initiate post-conversation analysis. This endpoint should only be called on a started, non-finished conversation. It can only be called when the previous [`Start a conversation`](start-conversation) and [`Interact with a conversation`](interact-with-conversation) calls have finished. If the conversation has no messages, the conversation is deleted. It''s possible for some conversations to automatically finish during an [`Interact with a conversation`](interact-with-conversation) call (for instance, if the user explicitly sends a message indicating that they''re done with the conversation). In that case, this endpoint shouldn''t be called, as the [`Interact with a conversation`](interact-with-conversation) endpoint automatically wraps up the conversation. #### Permissions This endpoint requires the following permissions: * `User:UpdateUserInfo` on the user who started the conversation. * `Conversation:FinishConversation` on the conversation.' operationId: finish-conversation parameters: - name: conversation_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the conversation to finish. title: Conversation Id description: The identifier of the conversation to finish. - name: organization in: path required: true schema: type: string title: Organization - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol responses: '204': description: Succeeded. '404': description: Specified organization or conversation is not found. '422': description: Invalid request path parameter failed validation. '409': description: The specified conversation is already finished, or a related operation is in process. '400': description: The conversation has no interactions. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 5 requests per minute for this endpoint. /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses: post: tags: - Conversation summary: Recommend responses for interaction description: 'Generate a recommended response for the user to send based on the existing chat history. This should be called when the most recent interaction had concluded for a while but the user still hasn''t responded. #### Permissions: This endpoint requires the following permissions: * `Conversation:GetRecommendedResponses` on this conversation.' operationId: recommend-responses-for-interaction parameters: - name: conversation_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the conversation. title: Conversation Id description: The identifier of the conversation. - name: interaction_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the most recent interaction. title: Interaction Id description: The identifier of the most recent interaction. - name: organization in: path required: true schema: type: string title: Organization - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol requestBody: content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__recommend_responses_for_interaction__Request' default: context: ' PERSONA: Name: User Background: A typical person seeking this service. --- SCENARIO: Name: Complete Service Objective: Successfully complete the service interaction. Instructions: Engage naturally with the agent to achieve the service objective. ' responses: '200': description: Succeeded. content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__recommend_responses_for_interaction__Response' '422': description: Invalid request path parameter failed validation. '404': description: Specified organization or conversation is not found. '400': description: The conversation is finished, or the supplied interaction ID doesn't correspond to the latest, completed interaction. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 20 requests per minute for this endpoint. /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/insights: get: tags: - Conversation summary: Get interaction insights description: 'Retrieve insights about the agent''s message for a given interaction. #### Permissions: This endpoint requires the following permissions: * `Conversation:GetInteractionInsights` on the conversation. * `Organization:GetServiceHierarchicalStateMachine` on the state machine that the current interaction is in. This endpoint may be impacted by the following permissions: * Only reflection messages for which the authenticated user has the `Conversation:GetMessage` permission are included in the response.' operationId: get-interaction-insights parameters: - name: conversation_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the conversation. title: Conversation Id description: The identifier of the conversation. - name: interaction_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the interaction. title: Interaction Id description: The identifier of the interaction. - name: organization in: path required: true schema: type: string title: Organization - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol responses: '200': description: Succeeded. content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__get_interaction_insights__Response' '404': description: Specified organization, conversation, or interaction is not found. '422': description: Invalid request path parameter failed validation. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 20 requests per minute for this endpoint. /v1/{organization}/conversation/{conversation_id}/interact: post: tags: - Conversation summary: Interact with a conversation description: 'Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response. A `UserMessageAvailableEvent` will be the first event in the response, which includes the user message if it''s sent as text, or the transcribed message if it''s sent as voice. A series of `CurrentAgentActionEvent`s will follow, which indicates steps in the agent''s thinking process. Then the agent message is generated sequentially in pieces, with each piece being sent as a `NewMessageEvent` in the response. After all the pieces are sent, an `InteractionCompleteEvent` is sent. Depending on the `conversation_completed` property in this event, the conversation will be awaiting a new message from the user, or it might automatically end (for instance, because the user message indicates the user wants to end the session), while the conversation is marked as finished and the post-conversation analysis asynchronously initiated. The connection will then terminate. Any further action on the conversation is only allowed after the connection is terminated. A 200 status code doesn''t indicate the successful completion of this endpoint, because the status code is transmitted before the stream starts. At any point during the stream, an `ErrorEvent` might be sent, which indicates that an error has occurred. The connection will be immediately closed after. This endpoint can only be called on a conversation that has started but not finished. #### Permissions This endpoint requires the following permissions: * `User:UpdateUserInfo` on the user who started the conversation. * `Conversation:InteractWithConversation` on the conversation. This endpoint may be impacted by the following permissions: * `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.' operationId: interact-with-conversation parameters: - name: conversation_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the conversation to send a message to. title: Conversation Id description: The identifier of the conversation to send a message to. - name: organization in: path required: true schema: type: string title: Organization - name: request_format in: query required: true schema: enum: - text - voice type: string description: The format in which the user message is delivered to the server. title: Request Format description: The format in which the user message is delivered to the server. - name: response_format in: query required: true schema: enum: - text - voice type: string description: The format of the response that will be sent to the user. title: Response Format description: The format of the response that will be sent to the user. - name: current_agent_action_type in: query required: false schema: type: string description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`. default: ^.*$ title: Current Agent Action Type description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`. - name: request_audio_config in: query required: false schema: anyOf: - $ref: '#/components/schemas/UserMessageAudioConfig' - type: 'null' description: Configuration for the user message audio. This is only required if `request_format` is set to `voice`. title: Request Audio Config description: Configuration for the user message audio. This is only required if `request_format` is set to `voice`. - name: content-type in: header required: true schema: type: string pattern: ^multipart\/form-data; boundary=.+$ description: The content type of the request body, which must be `multipart/form-data` followed by a boundary. title: Content-Type description: The content type of the request body, which must be `multipart/form-data` followed by a boundary. - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol responses: '200': description: ' Succeeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available, so the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection. ' content: application/x-ndjson: schema: type: object $ref: '#/components/schemas/src__app__endpoints__conversation__interact_with_conversation__Response' '422': description: Invalid request path parameter or request body failed validation. '404': description: Specified organization or conversation is not found. '409': description: The specified conversation is already finished, or a related operation is in process. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '415': description: The format of the supplied audio file is not supported. '429': description: The user has exceeded the rate limit of 15 requests per minute for this endpoint. '400': description: ' This may occur for the following reasons: * The user message is empty. * The preferred language does not support voice transcription or response. * The `response_audio_format` field is not set when voice output is requested. * The timestamps for external event messages are not in the past. * The timestamps for external event messages are inconsistent with the conversation. * The agent does not have voice config specified.' '408': description: The request body stream timed out. requestBody: required: true content: multipart/form-data: schema: oneOf: - properties: initial_message_type: const: external-event title: Initial Message Type type: string recorded_message: minLength: 1 type: string external_event_message_content: default: [] description: The contents of external event messages to be inserted before the initial message, in chronological order. items: minLength: 1 type: string title: External Event Message Content type: array external_event_message_timestamp: default: [] description: The timestamps of external event messages to be inserted before the initial message, in chronological order. items: format: date-time type: string title: External Event Message Timestamp type: array required: - initial_message_type - recorded_message title: ExternalEventClientMessageRequestBody type: object - properties: initial_message_type: const: user-message title: Initial Message Type type: string recorded_message: minLength: 1 type: string external_event_message_content: default: [] description: The contents of external event messages to be inserted before the initial message, in chronological order. items: minLength: 1 type: string title: External Event Message Content type: array external_event_message_timestamp: default: [] description: The timestamps of external event messages to be inserted before the initial message, in chronological order. items: format: date-time type: string title: External Event Message Timestamp type: array required: - initial_message_type - recorded_message title: UserMessageClientMessageRequestBody type: object - properties: initial_message_type: const: skip title: Initial Message Type type: string recorded_message: description: The body of the initial message, which must be empty. maxLength: 0 title: Recorded Message type: string external_event_message_content: default: [] description: Must be empty, as external event messages cannot be sent with skips. items: minLength: 1 type: string maxItems: 0 title: External Event Message Content type: array external_event_message_timestamp: default: [] description: Must be empty, as external event messages cannot be sent with skips. items: format: date-time type: string maxItems: 0 title: External Event Message Timestamp type: array required: - initial_message_type - recorded_message title: SkipClientMessageRequestBody type: object /v1/{organization}/conversation/{conversation_id}/messages/{message_id}/source: get: tags: - Conversation summary: Retrieve message source description: 'Retrieve the raw source of the given message. It''s only applicable to messages that did not originate as texts. #### Permissions This endpoint requires the following permissions: * `Conversation:GetMessage` on the the message.' operationId: retrieve-message-source parameters: - name: organization in: path required: true schema: type: string title: Organization - name: conversation_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the conversation. title: Conversation Id description: The identifier of the conversation. - name: message_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ description: The identifier of the message. title: Message Id description: The identifier of the message. - name: long_lived in: query required: false schema: type: boolean description: Whether to generate a long-lived URL which lasts 12 hours. For security purposes, it's recommended to set this to false as much as possible. default: false title: Long Lived description: Whether to generate a long-lived URL which lasts 12 hours. For security purposes, it's recommended to set this to false as much as possible. - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol responses: '200': description: Succeeded. content: application/json: schema: {} '404': description: Specified organization or message is not found. '400': description: The message is a text message. '422': description: Invalid request path parameter failed validation. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 30 request per minute for this endpoint. /v1/{organization}/conversation/conversation_starter: post: tags: - Conversation summary: Generate conversation starters for a service description: 'Generate conversation starters for a service. #### Permissions This endpoint requires the following permissions: * `Conversation:CreateConversation` for a hypothetical new conversation created using the same setting.' operationId: generate-conversation-starter parameters: - name: organization in: path required: true schema: type: string title: Organization - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__generate_conversation_starter__Request' responses: '200': description: Succeeded. content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__generate_conversation_starter__Response' '404': description: Service not found. '422': description: Invalid request path parameter or request body failed validation. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 10 requests per minute for this endpoint. /v1/{organization}/conversation/{conversation_id}/tags/: post: tags: - Conversation summary: Modify tags of a conversation description: 'Modify the tags of a conversation. #### Permissions This endpoint requires the following permissions: * `Conversation:ModifyConversation` for the conversation to modify tags for.' operationId: modify-tags-of-conversation parameters: - name: organization in: path required: true schema: type: string title: Organization - name: conversation_id in: path required: true schema: type: string pattern: ^[a-f0-9]{24}$ title: Conversation Id - name: x-mongo-cluster-name in: header required: false schema: anyOf: - type: string - type: 'null' description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. title: X-Mongo-Cluster-Name description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database. - name: Sec-WebSocket-Protocol in: header required: false schema: type: array items: type: string default: [] title: Sec-Websocket-Protocol requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/src__app__endpoints__conversation__modify_tags_of_conversation__Request' responses: '204': description: Succeeded. '422': description: Invalid request path parameter or request body failed validation. '404': description: Specified organization or conversation is not found. '400': description: The conversation cannot contain more than 20 tags. '401': description: Invalid authorization credentials. '403': description: Missing required permissions. '503': description: The service is going through temporary maintenance. '429': description: The user has exceeded the rate limit of 50 requests per minute for this endpoint. components: schemas: NavigateStateMachineAgentActionEvent: anyOf: - $ref: '#/components/schemas/NavigateStateMachineDynamicBehaviorOverrideEvent' - $ref: '#/components/schemas/NavigateStateMachineActionStateActionSelectedEvent' - $ref: '#/components/schemas/NavigateStateMachineDecisionStateDecisionStartedEvent' - $ref: '#/components/schemas/NavigateStateMachineExitConditionSelectedEvent' - $ref: '#/components/schemas/NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent' - $ref: '#/components/schemas/NavigateStateMachineRecallStateStaticQueriesRetrievedEvent' - $ref: '#/components/schemas/NavigateStateMachineRecallStateActiveMemoryRetrievedEvent' - $ref: '#/components/schemas/NavigateStateMachineReflectionStatePromptRetrievedEvent' - $ref: '#/components/schemas/NavigateStateMachineReflectionStateReflectionGeneratedEvent' - $ref: '#/components/schemas/NavigateStateMachineAnnotationStateAnnotationRetrievedEvent' - $ref: '#/components/schemas/NavigateStateMachineStateTransitionedEvent' - $ref: '#/components/schemas/GenerateToolParamsEvent' - $ref: '#/components/schemas/NavigateStateMachineToolCallStateToolOutputAvailableEvent' - $ref: '#/components/schemas/ToolCallStartedEvent' - $ref: '#/components/schemas/ToolCallEndedEvent' - $ref: '#/components/schemas/ActionTooLongEvent' ConversationInstance: properties: id: type: string title: Id description: The identifier of the conversation. user_id: type: string title: User Id description: The identifier of the user who started this conversation. created_at: type: string format: date-time title: Created At description: The timestamp at which this conversation was started. is_finished: type: boolean title: Is Finished description: Whether the conversation is finished. is_analyzed: type: boolean title: Is Analyzed description: Whether the conversation has gone through the post-conversation analysis after finishing. completed_post_processings: items: $ref: '#/components/schemas/PostAnalysisType' type: array title: Completed Post Processings description: A list of post-processing types that have been completed for this conversation. final_message: type: string title: Final Message description: 'The most recent message from the conversation. This field is empty if the authenticated user has no `Conversation:GetMessage` permission on the final message.' service_id: type: string title: Service Id description: The ID of the service that this conversation uses. version_set_info: anyOf: - $ref: '#/components/schemas/VersionSetInfo' - type: 'null' description: Info of the service version set that this conversation uses. This field is only populated if the authenticated user has the `Service.GetVersionSet` permission on the version set. num_messages: type: integer title: Num Messages description: The number of messages in this conversation. tags: additionalProperties: anyOf: - type: string - type: 'null' type: object title: Tags description: The tags associated with this conversation. type: object required: - id - user_id - created_at - is_finished - is_analyzed - completed_post_processings - final_message - service_id - version_set_info - num_messages - tags title: ConversationInstance VersionSetInfo: properties: name: type: string title: Name description: The name of the version set. If the value is `unknown`, it means the conversation was created before this field was introduced and the version set name cannot be retroactively determined. agent_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Agent Version Info description: The ID of the agent and version number used in this conversation. service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Service Hierarchical State Machine Version Info description: The ID of the state machine and version number used in this conversation. llm_model_preferences: additionalProperties: $ref: '#/components/schemas/LLMConfig-Output' type: object title: Llm Model Preferences description: The LLM model preferences for this version set. type: object required: - name - agent_version_info - service_hierarchical_state_machine_version_info - llm_model_preferences title: VersionSetInfo amigo_lib__pydantic__base_model__StrippedNonemptyString__1: type: string minLength: 1 src__app__endpoints__conversation__generate_conversation_starter__Request: properties: service_id: type: string pattern: ^[a-f0-9]{24}$ title: Service Id description: The identifier of the service to create a conversation starter for. service_version_set_name: type: string title: Service Version Set Name description: The version set of the service to use. If not provided, the `release` version set is used. default: release facets: items: $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1' type: array minItems: 1 title: Facets description: The facets that the generated conversation starter should be about. Each generated starter is related to some of these facets. min_count: type: integer maximum: 10.0 exclusiveMinimum: 0.0 title: Min Count description: The minimum (inclusive) number of conversation starters to generate. max_count: type: integer maximum: 10.0 exclusiveMinimum: 0.0 title: Max Count description: The maximum (inclusive) number of conversation starters to generate. generation_instructions: $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1' description: The instruction for the conversation starter generation. type: object required: - service_id - facets - min_count - max_count - generation_instructions title: Request NavigateStateMachineRecallStateStaticQueriesRetrievedEvent: properties: type: type: string const: navigate-state-machine-recall-state-static-queries-retrieved title: Type default: navigate-state-machine-recall-state-static-queries-retrieved static_queries: items: type: string type: array title: Static Queries description: The static queries that the agent has retrieved. type: object required: - static_queries title: NavigateStateMachineRecallStateStaticQueriesRetrievedEvent description: Indicating that the agent has retrieved the static queries in the current the recall state. EngageUserMessageFragmentGeneratedEvent: properties: type: type: string const: engage-user-message-fragment-generated title: Type default: engage-user-message-fragment-generated index: type: integer title: Index description: The index of the fragment in the agent response. fragment: type: string title: Fragment description: The fragment of the agent response that has been generated. is_final: type: boolean title: Is Final description: Whether this fragment is the final fragment of the agent response. type: object required: - index - fragment - is_final title: EngageUserMessageFragmentGeneratedEvent description: Indicating that the agent has generated a fragment of the agent response. CheckIfActiveMemoryNeededAgentActionEvent: properties: type: type: string const: check-if-active-memory-needed-completed title: Type default: check-if-active-memory-needed-completed queries: items: type: string type: array title: Queries type: object required: - queries title: CheckIfActiveMemoryNeededCompletedEvent LLMConfig-Output: properties: llm_name: type: string title: Llm Name description: The name of the LLM to use. params: additionalProperties: true type: object title: Params description: LLM-specific parameters to use. default: {} type: object required: - llm_name title: LLMConfig NavigateStateMachineDynamicBehaviorOverrideEvent: properties: type: type: string const: navigate-state-machine-dynamic-behavior-override title: Type default: navigate-state-machine-dynamic-behavior-override overriding_instructions: type: boolean title: Overriding Instructions description: Whether the dynamic behavior set is overriding instructions during this interaction. overriding_tool_candidates: type: boolean title: Overriding Tool Candidates description: Whether the dynamic behavior set is overriding the tool candidates during this interaction. type: object required: - overriding_instructions - overriding_tool_candidates title: NavigateStateMachineDynamicBehaviorOverrideEvent description: Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state. src__app__endpoints__conversation__generate_conversation_starter__Response: properties: prompts: items: $ref: '#/components/schemas/Prompt' type: array title: Prompts description: The generated prompts. type: object required: - prompts title: Response ErrorEvent: properties: type: type: string const: error title: Type default: error http_error_code: type: integer title: Http Error Code description: The HTTP status code of the error. error_description: type: string title: Error Description description: A description of the error. type: object required: - http_error_code - error_description title: ErrorEvent description: 'Emitted when there is an error during the stream. This event could be emitted even if the request returns with a 200. If received before an `interaction-complete` event, the client should consider the entire interaction void and retry. If received after, then the conversation has completed and an error occurred during the post-processing, so the client should consider the interaction valid and saved, but manually call the `FinishConversation` endpoint to retry the post-processing.' src__app__endpoints__conversation__modify_tags_of_conversation__Request: properties: updates: additionalProperties: anyOf: - $ref: '#/components/schemas/StrippedNonemptyString___w__s_____' - type: 'null' propertyNames: $ref: '#/components/schemas/StrippedNonemptyString___w__s_____' type: object maxProperties: 20 title: Updates description: A mapping of tags to add or update on the conversation. Existing tags not included here remain unchanged. default: {} deletes: items: $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1' type: array uniqueItems: true title: Deletes description: A list of tags to remove from the conversation. default: [] type: object title: Request NavigateStateMachineAnnotationStateAnnotationRetrievedEvent: properties: type: type: string const: navigate-state-machine-annotation-state-annotation-retrieved title: Type default: navigate-state-machine-annotation-state-annotation-retrieved annotation: type: string title: Annotation type: object required: - annotation title: NavigateStateMachineAnnotationStateAnnotationRetrievedEvent description: Indicating that the agent has retrieved the annotation in the current annotation state. Format: type: string enum: - text - voice StrippedNonemptyString___w__s______: type: string minLength: 1 pattern: ^[\w\s_]+$ NavigateStateMachineActionStateActionSelectedEvent: properties: type: type: string const: navigate-state-machine-action-state-action-selected title: Type default: navigate-state-machine-action-state-action-selected action: type: string title: Action type: object required: - action title: NavigateStateMachineActionStateActionSelectedEvent description: Indicating that the agent has selected an action from the current state. AnnotationStateTransitionLog: properties: previous_state: type: string title: Previous State description: Name of the previous state to transition from. previous_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Previous Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the previous state is in. next_state: type: string title: Next State description: Name of the next state to transition to. next_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the next state is in. type: type: string const: annotation title: Type description: The type of the state transition log, which is the type of the state we're transitioning from. default: annotation inner_thought_message_id: type: string title: Inner Thought Message Id description: The identifier of the inserted inner thought message. type: object required: - previous_state - previous_service_hierarchical_state_machine_version_info - next_state - next_service_hierarchical_state_machine_version_info - inner_thought_message_id title: AnnotationStateTransitionLog NewMessageEvent: properties: type: type: string const: new-message title: Type default: new-message message: type: string title: Message description: 'Either the raw-text piece or a base-64 encoded string of bytes representing the piece in alternative forms. If it represents audio, the audios are in PCM16 format.' transcript_alignment: anyOf: - items: prefixItems: - type: integer - type: string type: array maxItems: 2 minItems: 2 type: array - type: 'null' title: Transcript Alignment description: 'Transcript of the ongoing audio message and how they align with the audio, if the message is in audio format. Otherwise, it''s `None`. This is an array of tuples, where each tuple contains a character and an integer indicating the milliseconds since the audio started when the character is spoken. Note that this field might not be defined for some events that transmit audio bytes -- in that case, the alignment information for that chunk was already included in the `transcript_alignment` field in the previous event.' stop: type: boolean title: Stop description: Whether this is the last piece of the agent message. sequence_number: type: integer title: Sequence Number description: The sequence number of this piece in the agent message. message_id: type: string title: Message Id description: 'The identifier of this agent message. ' type: object required: - message - transcript_alignment - stop - sequence_number - message_id title: NewMessageEvent description: Emitted when a new piece of the agent message is available. NavigateStateMachineExitConditionSelectedEvent: properties: type: type: string const: navigate-state-machine-exit-condition-selected title: Type default: navigate-state-machine-exit-condition-selected exit_condition: type: string title: Exit Condition description: The exit condition that the agent has selected. next_state_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next State State Machine Version Info description: The state machine version info of the next state. next_state_name: type: string title: Next State Name description: The name of the next state. type: object required: - exit_condition - next_state_state_machine_version_info - next_state_name title: NavigateStateMachineExitConditionSelectedEvent description: Indicating that the agent has selected an exit condition from the current action or decision state. NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent: properties: type: type: string const: navigate-state-machine-recall-state-dynamic-queries-generated title: Type default: navigate-state-machine-recall-state-dynamic-queries-generated dynamic_queries: items: type: string type: array title: Dynamic Queries description: The dynamic queries that the agent has generated. requested_information: type: string title: Requested Information description: The information that the agent needs from the queries. type: object required: - dynamic_queries - requested_information title: NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent description: Indicating that the agent has generated dynamic queries in the current the recall state. SelectDynamicBehaviorAgentActionEvent: oneOf: - $ref: '#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent' - $ref: '#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent' - $ref: '#/components/schemas/SelectDynamicBehaviorCompletedEvent' discriminator: propertyName: type mapping: select-dynamic-behavior-completed: '#/components/schemas/SelectDynamicBehaviorCompletedEvent' select-dynamic-behavior-relevance-retrieval-completed: '#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent' select-dynamic-behavior-vector-generated: '#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent' SelectDynamicBehaviorCompletedEvent: properties: type: type: string const: select-dynamic-behavior-completed title: Type default: select-dynamic-behavior-completed selected_dynamic_behavior_set_version_info: anyOf: - prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 - type: 'null' title: Selected Dynamic Behavior Set Version Info previous_selected_dynamic_behavior_set_version_info: anyOf: - prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 - type: 'null' title: Previous Selected Dynamic Behavior Set Version Info type: object required: - selected_dynamic_behavior_set_version_info - previous_selected_dynamic_behavior_set_version_info title: SelectDynamicBehaviorCompletedEvent amigo_lib__pydantic__base_model__StrippedNonemptyString__4: type: string maxLength: 100 minLength: 1 GenerateToolParamsEvent: anyOf: - $ref: '#/components/schemas/GenerateToolParamsDesignatedToolRetrievedEvent' - $ref: '#/components/schemas/GenerateToolParamsDesignatedToolCallParamsGeneratedEvent' - $ref: '#/components/schemas/ActionTooLongEvent' - $ref: '#/components/schemas/ToolCallStartedEvent' - $ref: '#/components/schemas/ToolCallEndedEvent' RecallStateTransitionLog: properties: previous_state: type: string title: Previous State description: Name of the previous state to transition from. previous_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Previous Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the previous state is in. next_state: type: string title: Next State description: Name of the next state to transition to. next_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the next state is in. type: type: string const: recall title: Type description: The type of the state transition log, which is the type of the state we're transitioning from. default: recall performed_queries: items: type: string type: array title: Performed Queries description: A list of queries that were actually performed during this state. This does not include queries included in the states that are duplicates of queries performed previously in this conversation. type: object required: - previous_state - previous_service_hierarchical_state_machine_version_info - next_state - next_service_hierarchical_state_machine_version_info - performed_queries title: RecallStateTransitionLog EngageUserAgentActionEvent: oneOf: - $ref: '#/components/schemas/EngageUserDynamicBehaviorOverrideEvent' - $ref: '#/components/schemas/EngageUserMessageFragmentGeneratedEvent' - $ref: '#/components/schemas/ToolCallStartedEvent' - $ref: '#/components/schemas/ToolCallEndedEvent' - $ref: '#/components/schemas/ActionTooLongEvent' discriminator: propertyName: type mapping: action-too-long: '#/components/schemas/ActionTooLongEvent' engage-user-dynamic-behavior-override: '#/components/schemas/EngageUserDynamicBehaviorOverrideEvent' engage-user-message-fragment-generated: '#/components/schemas/EngageUserMessageFragmentGeneratedEvent' tool-call-ended: '#/components/schemas/ToolCallEndedEvent' tool-call-started: '#/components/schemas/ToolCallStartedEvent' InteractionCompleteEvent: properties: type: type: string const: interaction-complete title: Type default: interaction-complete message_id: type: string title: Message Id description: The identifier of the agent message in this interaction. interaction_id: type: string title: Interaction Id description: The identifier of this interaction. full_message: type: string title: Full Message description: A structure containing either the content of the message if it's text, or the transcript of the message if it's audio. conversation_completed: type: boolean title: Conversation Completed description: Whether the conversation is auto-completed after this interaction. type: object required: - message_id - interaction_id - full_message - conversation_completed title: InteractionCompleteEvent description: Emitted when the interaction is complete and committed to database. This event is only emitted after all `NewMessageEvent`s are emitted. NavigateStateMachineRecallStateActiveMemoryRetrievedEvent: properties: type: type: string const: navigate-state-machine-recall-state-active-memory-retrieved title: Type default: navigate-state-machine-recall-state-active-memory-retrieved queries_and_responses: items: prefixItems: - type: string - type: string type: array maxItems: 2 minItems: 2 type: array title: Queries And Responses description: A list of tuples of queries and responses. type: object required: - queries_and_responses title: NavigateStateMachineRecallStateActiveMemoryRetrievedEvent description: Indicating that the agent has retrieved the active memory in the current the recall state. ConversationEvent: anyOf: - $ref: '#/components/schemas/InteractionCompleteEvent' - $ref: '#/components/schemas/NewMessageEvent' - $ref: '#/components/schemas/CurrentAgentActionEvent' src__app__endpoints__conversation__create_conversation__Request: properties: service_id: type: string pattern: ^[a-f0-9]{24}$ title: Service Id description: The identifier of the service to create a conversation in. service_version_set_name: type: string title: Service Version Set Name description: The version set of the service to use. If not provided, the `release` version set is used. default: release initial_message: anyOf: - $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1' - type: 'null' description: The initial user or agent inner thought message to send to the service. If not provided, the conversation will start with an agent message. initial_message_type: anyOf: - type: string enum: - user-message - external-event - type: 'null' title: Initial Message Type description: The type of the `initial_message`. Can only be specified if `initial_message` is provided. tags: additionalProperties: anyOf: - $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__4' - type: 'null' propertyNames: $ref: '#/components/schemas/StrippedNonemptyString___w__s______' type: object maxProperties: 20 title: Tags description: A list of tags for the conversation. The key can only contain alphanumeric characters, underscores, or spaces. The value can only contain up to 100 characters. default: {} type: object required: - service_id title: Request ToolCallStartedEvent: properties: type: type: string const: tool-call-started title: Type default: tool-call-started tool_round_index: type: integer title: Tool Round Index description: Within the current LLM interaction, the round of tool call. tool_id: type: string title: Tool Id description: The ID of the tool being called. tool_version: type: string title: Tool Version description: The version of the tool being called. input_params: additionalProperties: true type: object title: Input Params description: The input parameters for the tool call. type: object required: - tool_round_index - tool_id - tool_version - input_params title: ToolCallStartedEvent description: Indicating that the agent has started executing a tool. NavigateStateMachineStateTransitionedEvent: properties: type: type: string const: navigate-state-machine-state-transitioned title: Type default: navigate-state-machine-state-transitioned prev_state: type: string title: Prev State description: The previous state. prev_state_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Prev State State Machine Version Info description: The state machine version info of the previous state. next_state: type: string title: Next State description: The next state. next_state_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next State State Machine Version Info description: The state machine version info of the next state. type: object required: - prev_state - prev_state_state_machine_version_info - next_state - next_state_state_machine_version_info title: NavigateStateMachineStateTransitionedEvent description: Indicating that the agent has transitioned to a new state. WorkingMemory: properties: content: type: string title: Content description: The content of the memory. context: type: string title: Context description: The context of the memory. type: object required: - content - context title: WorkingMemory src__app__endpoints__conversation__interact_with_conversation__Response: anyOf: - $ref: '#/components/schemas/ConversationEvent' - $ref: '#/components/schemas/UserMessageAvailableEvent' - $ref: '#/components/schemas/ErrorEvent' SelectDynamicBehaviorRelevanceRetrievalCompletedEvent: properties: type: type: string const: select-dynamic-behavior-relevance-retrieval-completed title: Type default: select-dynamic-behavior-relevance-retrieval-completed type: object title: SelectDynamicBehaviorRelevanceRetrievalCompletedEvent UserMessageAvailableEvent: properties: type: type: string const: user-message-available title: Type default: user-message-available message_id: type: string title: Message Id description: The identifier of the user message. user_message: type: string title: User Message description: The text of the user message. type: object required: - message_id - user_message title: UserMessageAvailableEvent description: Emitted when the full text of the user message is available. In particular, for voice messages, this event is emitted when the transcription of the user message is complete. It's the first event in the response stream. src__app__amigo__service__conversation__Action: anyOf: - $ref: '#/components/schemas/SelectDynamicBehaviorAgentActionEvent' - $ref: '#/components/schemas/CheckIfActiveMemoryNeededAgentActionEvent' - $ref: '#/components/schemas/ExtractActiveMemoriesAgentActionEvent' - $ref: '#/components/schemas/NavigateStateMachineAgentActionEvent' - $ref: '#/components/schemas/EngageUserAgentActionEvent' DecisionStateTransitionLog: properties: previous_state: type: string title: Previous State description: Name of the previous state to transition from. previous_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Previous Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the previous state is in. next_state: type: string title: Next State description: Name of the next state to transition to. next_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the next state is in. type: type: string const: decision title: Type description: The type of the state transition log, which is the type of the state we're transitioning from. default: decision previous_state_exit_condition_description: type: string title: Previous State Exit Condition Description description: The description of the exit condition that led to the transition to the next state. tool_call_logs: items: items: $ref: '#/components/schemas/ToolCallLog' type: array type: array title: Tool Call Logs description: A list of tool call logs that were performed during the `SelectNextActionForDecisionState` LLM call during this state. type: object required: - previous_state - previous_service_hierarchical_state_machine_version_info - next_state - next_service_hierarchical_state_machine_version_info - previous_state_exit_condition_description - tool_call_logs title: DecisionStateTransitionLog JumpbackStateTransitionLog: properties: previous_state: type: string title: Previous State description: Name of the previous state to transition from. previous_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Previous Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the previous state is in. next_state: type: string title: Next State description: Name of the next state to transition to. next_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the next state is in. type: type: string const: jumpback title: Type description: The type of the state transition log, which is the type of the state we're transitioning from. default: jumpback type: object required: - previous_state - previous_service_hierarchical_state_machine_version_info - next_state - next_service_hierarchical_state_machine_version_info title: JumpbackStateTransitionLog ToolCallStateTransitionLog: properties: previous_state: type: string title: Previous State description: Name of the previous state to transition from. previous_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Previous Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the previous state is in. next_state: type: string title: Next State description: Name of the next state to transition to. next_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the next state is in. type: type: string const: tool-call title: Type description: The type of the state transition log, which is the type of the state we're transitioning from. default: tool-call tool_call_logs: items: items: $ref: '#/components/schemas/ToolCallLog' type: array type: array title: Tool Call Logs description: A list of tool call logs that were performed during this state, except for the tool call for the designated tool call. designated_tool_call_log: $ref: '#/components/schemas/ToolCallLog' description: The tool call log for the designated tool call in this state. type: object required: - previous_state - previous_service_hierarchical_state_machine_version_info - next_state - next_service_hierarchical_state_machine_version_info - tool_call_logs - designated_tool_call_log title: ToolCallStateTransitionLog ActionTooLongEvent: properties: type: type: string const: action-too-long title: Type default: action-too-long filler: type: string title: Filler description: 'A filler that can be played while waiting for the action to complete. If the audio filler exists, this is monochannel, 16-bit PCM WAV audio (at sample rate 16kHz) encoded in base64 encoding. Otherwise, this is the text corresponding to the audio filler.' previously_started_event: title: Previously Started Event description: The previously started event that is taking too long. type: object required: - filler - previously_started_event title: ActionTooLongEvent description: 'Indicating that a previously-started action of the agent is taking too long. This event supplies a filler text that can be displayed while waiting for the action to complete.' src__app__endpoints__conversation__get_conversations__Response: properties: conversations: items: $ref: '#/components/schemas/ConversationInstance' type: array title: Conversations description: The conversations satisfying the filters. has_more: type: boolean title: Has More description: Whether there are more conversations to retrieve. continuation_token: anyOf: - type: integer - type: 'null' title: Continuation Token description: A token to supply to the next request to retrieve the next page of conversations. Only populated if `has_more` is `True`. type: object required: - conversations - has_more - continuation_token title: Response ReflectionStateTransitionLog: properties: previous_state: type: string title: Previous State description: Name of the previous state to transition from. previous_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Previous Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the previous state is in. next_state: type: string title: Next State description: Name of the next state to transition to. next_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the next state is in. type: type: string const: reflection title: Type description: The type of the state transition log, which is the type of the state we're transitioning from. default: reflection inner_thought_message_id: type: string title: Inner Thought Message Id description: The identifier of the inserted inner thought message. tool_call_logs: items: items: $ref: '#/components/schemas/ToolCallLog' type: array type: array title: Tool Call Logs description: A list of tool call logs that were performed during the `GenerateReflection` LLM call during this state. type: object required: - previous_state - previous_service_hierarchical_state_machine_version_info - next_state - next_service_hierarchical_state_machine_version_info - inner_thought_message_id - tool_call_logs title: ReflectionStateTransitionLog PCMUserMessageAudioConfig: properties: type: type: string const: pcm title: Type default: pcm frame_rate: type: integer maximum: 44100.0 minimum: 4000.0 title: Frame Rate n_channels: type: integer const: 1 title: N Channels sample_width: type: integer enum: - 2 - 4 title: Sample Width type: object required: - frame_rate - n_channels - sample_width title: PCMUserMessageAudioConfig MP3UserMessageAudioConfig: properties: type: type: string const: mp3 title: Type default: mp3 type: object title: MP3UserMessageAudioConfig PostAnalysisType: type: string enum: - generate-user-models - extract-memories - compute-metrics UserMessageAudioConfig: oneOf: - $ref: '#/components/schemas/MP3UserMessageAudioConfig' - $ref: '#/components/schemas/PCMUserMessageAudioConfig' discriminator: propertyName: type mapping: mp3: '#/components/schemas/MP3UserMessageAudioConfig' pcm: '#/components/schemas/PCMUserMessageAudioConfig' ExtractActiveMemoriesAgentActionEvent: properties: type: type: string const: extract-active-memories-completed title: Type default: extract-active-memories-completed queries_and_responses: items: prefixItems: - type: string - type: string type: array maxItems: 2 minItems: 2 type: array title: Queries And Responses type: object required: - queries_and_responses title: ExtractActiveMemoriesCompletedEvent EngageUserDynamicBehaviorOverrideEvent: properties: type: type: string const: engage-user-dynamic-behavior-override title: Type default: engage-user-dynamic-behavior-override overriding_instructions: type: boolean title: Overriding Instructions description: Whether the dynamic behavior set is overriding instructions during this interaction. overriding_tool_candidates: type: boolean title: Overriding Tool Candidates description: Whether the dynamic behavior set is overriding the tool candidates during this interaction. type: object required: - overriding_instructions - overriding_tool_candidates title: EngageUserDynamicBehaviorOverrideEvent description: Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state. MessageType: type: string enum: - user-message - agent-message - agent-inner-thought - external-event MessageInstance: properties: id: type: string title: Id interaction_id: type: string title: Interaction Id description: The identifier of the interaction. created_at: type: string format: date-time title: Created At description: The time at which this message was created. sender: type: string title: Sender description: A human-friendly name of the sender of the message. message: type: string title: Message description: The text content of the message. format: $ref: '#/components/schemas/Format' description: The format in which the message was delivered. message_type: $ref: '#/components/schemas/MessageType' description: The type of the message. type: object required: - id - interaction_id - created_at - sender - message - format - message_type title: MessageInstance CurrentAgentActionEvent: properties: type: type: string const: current-agent-action title: Type default: current-agent-action action: $ref: '#/components/schemas/src__app__amigo__service__conversation__Action' description: The type of action the agent is performing right now. type: object required: - action title: CurrentAgentActionEvent description: 'Emitted when an agent is about to perform an action that aids in the generation of the response. This is emitted before any `NewMessageEvent` is emitted.' NavigateStateMachineReflectionStateReflectionGeneratedEvent: properties: type: type: string const: navigate-state-machine-reflection-state-reflection-generated title: Type default: navigate-state-machine-reflection-state-reflection-generated reflection: type: string title: Reflection description: The reflection that the agent has generated. type: object required: - reflection title: NavigateStateMachineReflectionStateReflectionGeneratedEvent description: Indicating that the agent has generated the reflection in the current reflection state. ToolCallEndedEvent: properties: type: type: string const: tool-call-ended title: Type default: tool-call-ended tool_round_index: type: integer title: Tool Round Index description: Within the current LLM interaction, the round of tool call. tool_id: type: string title: Tool Id description: The ID of the tool being called. tool_version: type: string title: Tool Version description: The version of the tool being called. input_parameters: additionalProperties: true type: object title: Input Parameters description: The input parameters for the tool call. result: type: string title: Result description: The result of the tool call. duration: type: number title: Duration description: The duration of the tool call in seconds. type: object required: - tool_round_index - tool_id - tool_version - input_parameters - result - duration title: ToolCallEndedEvent description: Indicating that the agent has finished executing a tool. NavigateStateMachineReflectionStatePromptRetrievedEvent: properties: type: type: string const: navigate-state-machine-reflection-state-prompt-retrieved title: Type default: navigate-state-machine-reflection-state-prompt-retrieved prompt: type: string title: Prompt type: object required: - prompt title: NavigateStateMachineReflectionStatePromptRetrievedEvent description: Indicating that the agent has retrieved the prompt in the current reflection state. GenerateToolParamsDesignatedToolRetrievedEvent: properties: type: type: string const: designated-tool-retrieved title: Type default: designated-tool-retrieved tool_id: type: string title: Tool Id description: The ID of the tool being called. tool_version: type: string title: Tool Version description: The version of the tool being called. type: object required: - tool_id - tool_version title: GenerateToolParamsDesignatedToolRetrievedEvent SelectDynamicBehaviorVectorGeneratedEvent: properties: type: type: string const: select-dynamic-behavior-vector-generated title: Type default: select-dynamic-behavior-vector-generated type: object title: SelectDynamicBehaviorVectorGeneratedEvent src__app__endpoints__conversation__get_conversation_messages__Response: properties: messages: items: $ref: '#/components/schemas/MessageInstance' type: array title: Messages description: The retrieved messages. has_more: type: boolean title: Has More description: Whether there are more, earlier messages in the conversation to retrieve. continuation_token: anyOf: - type: integer - type: 'null' title: Continuation Token description: The continuation token to use to retrieve the next set of messages. type: object required: - messages - has_more - continuation_token title: Response ConversationCreatedEvent: properties: type: type: string const: conversation-created title: Type default: conversation-created conversation_id: type: string title: Conversation Id description: The identifier of the newly created conversation. type: object required: - conversation_id title: ConversationCreatedEvent description: Emitted when the conversation is created. GenerateToolParamsDesignatedToolCallParamsGeneratedEvent: properties: type: type: string const: designated-tool-call-params-generated title: Type default: designated-tool-call-params-generated tool_id: type: string title: Tool Id description: The ID of the tool being called. tool_version: type: string title: Tool Version description: The version of the tool being called. tool_call_params: additionalProperties: true type: object title: Tool Call Params description: The generated tool call parameters. type: object required: - tool_id - tool_version - tool_call_params title: GenerateToolParamsDesignatedToolCallParamsGeneratedEvent StateTransitionLog: oneOf: - $ref: '#/components/schemas/ActionStateTransitionLog' - $ref: '#/components/schemas/DecisionStateTransitionLog' - $ref: '#/components/schemas/RecallStateTransitionLog' - $ref: '#/components/schemas/JumpbackStateTransitionLog' - $ref: '#/components/schemas/AnnotationStateTransitionLog' - $ref: '#/components/schemas/ReflectionStateTransitionLog' - $ref: '#/components/schemas/ToolCallStateTransitionLog' discriminator: propertyName: type mapping: action: '#/components/schemas/ActionStateTransitionLog' annotation: '#/components/schemas/AnnotationStateTransitionLog' decision: '#/components/schemas/DecisionStateTransitionLog' jumpback: '#/components/schemas/JumpbackStateTransitionLog' recall: '#/components/schemas/RecallStateTransitionLog' reflection: '#/components/schemas/ReflectionStateTransitionLog' tool-call: '#/components/schemas/ToolCallStateTransitionLog' NavigateStateMachineDecisionStateDecisionStartedEvent: properties: type: type: string const: navigate-state-machine-decision-state-decision-started title: Type default: navigate-state-machine-decision-state-decision-started type: object title: NavigateStateMachineDecisionStateDecisionStartedEvent description: Indicating that the agent has started making a decision in the current decision state. ActionStateTransitionLog: properties: previous_state: type: string title: Previous State description: Name of the previous state to transition from. previous_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Previous Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the previous state is in. next_state: type: string title: Next State description: Name of the next state to transition to. next_service_hierarchical_state_machine_version_info: prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 title: Next Service Hierarchical State Machine Version Info description: The identifier of the service hierarchical state machine that the next state is in. type: type: string const: action title: Type description: The type of the state transition log, which is the type of the state we're transitioning from. default: action previous_state_exit_condition_description: type: string title: Previous State Exit Condition Description description: The description of the exit condition that led to the transition to the next state. tool_call_logs: items: items: $ref: '#/components/schemas/ToolCallLog' type: array type: array title: Tool Call Logs description: A list of tool call logs that were performed during the `SelectNextAction` LLM call during this state. type: object required: - previous_state - previous_service_hierarchical_state_machine_version_info - next_state - next_service_hierarchical_state_machine_version_info - previous_state_exit_condition_description - tool_call_logs title: ActionStateTransitionLog src__app__endpoints__conversation__create_conversation__Response: oneOf: - $ref: '#/components/schemas/ConversationCreatedEvent' - $ref: '#/components/schemas/NewMessageEvent' - $ref: '#/components/schemas/InteractionCompleteEvent' - $ref: '#/components/schemas/CurrentAgentActionEvent' - $ref: '#/components/schemas/ErrorEvent' discriminator: propertyName: type mapping: conversation-created: '#/components/schemas/ConversationCreatedEvent' current-agent-action: '#/components/schemas/CurrentAgentActionEvent' error: '#/components/schemas/ErrorEvent' interaction-complete: '#/components/schemas/InteractionCompleteEvent' new-message: '#/components/schemas/NewMessageEvent' src__app__endpoints__conversation__recommend_responses_for_interaction__Request: properties: context: $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1' description: The context under which the recommended responses should be generated. default: ' PERSONA: Name: User Background: A typical person seeking this service. --- SCENARIO: Name: Complete Service Objective: Successfully complete the service interaction. Instructions: Engage naturally with the agent to achieve the service objective. ' type: object title: Request src__app__endpoints__conversation__recommend_responses_for_interaction__Response: properties: recommended_responses: items: type: string type: array title: Recommended Responses description: The recommended responses to the user. type: object required: - recommended_responses title: Response ToolCallLog: properties: tool_name: type: string title: Tool Name description: The name of the tool that was called. tool_id: type: string title: Tool Id description: The identifier of the tool that was called. tool_version: type: string title: Tool Version description: The version of the tool that was called. input: additionalProperties: true type: object title: Input description: The input to the tool call. output: anyOf: - type: string - type: 'null' title: Output description: The output of the tool call. If `None`, the tool call's output is ephemeral and not stored. duration: type: number title: Duration description: The duration of the tool call in seconds. type: object required: - tool_name - tool_id - tool_version - input - output - duration title: ToolCallLog StrippedNonemptyString___w__s_____: type: string minLength: 1 pattern: ^[\w\s]+$ NavigateStateMachineToolCallStateToolOutputAvailableEvent: properties: type: type: string const: navigate-state-machine-tool-call-state-tool-output-available title: Type default: navigate-state-machine-tool-call-state-tool-output-available tool_id: type: string title: Tool Id description: The ID of the tool being called. tool_version: type: string title: Tool Version description: The version of the tool being called. tool_output: type: string title: Tool Output description: The tool output. duration: type: number title: Duration description: The duration taken to receive the tool output in seconds. input_arguments: additionalProperties: true type: object title: Input Arguments description: The input arguments used for the tool call. type: object required: - tool_id - tool_version - tool_output - duration - input_arguments title: NavigateStateMachineToolCallStateToolOutputAvailableEvent description: Indicating that the agent has received the tool output in the current tool call state. Prompt: properties: prompt: type: string title: Prompt description: The generated prompt. facets: items: type: string type: array title: Facets description: The facets that the generated prompt is about. type: object required: - prompt - facets title: Prompt src__app__endpoints__conversation__get_interaction_insights__Response: properties: current_state_name: type: string title: Current State Name description: The state the agent is in. current_state_action: type: string title: Current State Action description: The action taken in the current state. current_state_objective: type: string title: Current State Objective description: The objective of the current state. state_transition_logs: items: $ref: '#/components/schemas/StateTransitionLog' type: array title: State Transition Logs description: The state transition log of the interaction. working_memory: items: $ref: '#/components/schemas/WorkingMemory' type: array title: Working Memory description: A list of active memories the agent used to generate the message. reflections: items: type: string type: array title: Reflections description: A list of reflections the agent made during the generation of this message. triggered_dynamic_behavior_set_version_info: anyOf: - prefixItems: - type: string - type: integer type: array maxItems: 2 minItems: 2 - type: 'null' title: Triggered Dynamic Behavior Set Version Info description: The ID and version number of the dynamic behavior set that was activated during this interaction. select_next_action_tool_call_logs: items: items: $ref: '#/components/schemas/ToolCallLog' type: array type: array title: Select Next Action Tool Call Logs description: A list of tool call logs that were performed during the final `SelectNextAction` LLM call during this interaction where an action was selected. engage_user_tool_call_logs: items: items: $ref: '#/components/schemas/ToolCallLog' type: array type: array title: Engage User Tool Call Logs description: A list of tool call logs that were performed during the `EngageUser` LLM call during this interaction. type: object required: - current_state_name - current_state_action - current_state_objective - state_transition_logs - working_memory - reflections - triggered_dynamic_behavior_set_version_info - select_next_action_tool_call_logs - engage_user_tool_call_logs title: Response securitySchemes: Bearer-Authorization: type: http scheme: bearer bearerFormat: JWT description: Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint. Bearer-Authorization-Organization: type: apiKey in: header name: X-ORG-ID description: An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization. Basic: type: http scheme: basic description: The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.