openapi: 3.0.0
info:
  title: agents API
  description: Set of endpoints related to agents-api
  contact:
    email: auradev@tid.es
tags:
  - name: agents
    description: Endpoints related to agents-api.
servers:
  - url: 'http://localhost:8989'
    description: Local server
  - url: 'https://svc-ap-current.auracognitive.com'
    description: ap-current
paths:
  /aura-services/v2/aiservices/agents/messages:
    post:
      tags:
        - agents
      description: Send a message to an agent for processing
      operationId: postAgentMessage
      x-router-controller: routes
      security:
        - ApiKeyHeaderAuth: [ ]
      parameters:
        - name: correlator
          in: header
          description: Unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
        - name: x-token-info
          in: header
          description:
            User authentication data. It might contain JWT object, plain or
            encoded (to keep backwards compatibility).
          required: true
          schema:
            type: string
        - name: x-correlator
          in: header
          description:
            unique identifier of a request to be used as correlator in all
            systems
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentApiMessageRequest"
            example:
              message:
                content: 
                  text: 'What is aura?'
              application:
                id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
                agent: '3dfde663-f24d-43f0-96b1-aecfdac0d9a5'
      responses:
        "200":
          $ref: "#/components/responses/ValidRequestAgent"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/InternalError"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  responses:
    ValidRequestAgent:
      description: Incoming HTTP request format is valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentApiMessageResponse"
          example:
            message:
              content:
                text: 'Aura is a cognitive platform that provides AI services.'
            session:
              id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
              sequence: 1
            metadata:
              source: 'agent'
              agent: '3dfde663-f24d-43f0-96b1-aecfdac0d9a5'
            parameters:
              temperature: 0.7
              max_tokens: 150
    InvalidRequest:
      description: Incoming HTTP request format is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    Unauthorized:
      description: Incoming HTTP request authorization is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    NotFound:
      description: Incoming HTTP request is not found
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    InternalError:
      description: Incoming HTTP request produces an internal error
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
  securitySchemes:
    ApiKeyHeaderAuth:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    AuraError:
      type: object
      description: Error response
      properties:
        code:
          type: string
          description: Unique id of the error
        message:
          type: string
          description: Specific and descriptive text of the error
        errors:
          description: With validation error. Swagger error information
          type: array
          items:
            type: object
    AgentMessage:
      type: object
      description: Contains the message to be sent to the agent
      required:
        - content
      properties:
        content:
          $ref: "#/components/schemas/AgentMessageContent"
    AgentMessageWithId:
      allOf:
        - $ref: '#/components/schemas/AgentMessage'
        - type: object
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier for the message
          required:
            - id
    AgentMessageContent:
      type: object
      description: Message content to be processed by the agent
      required:
        - text
      properties:
        text:
          type: string
          description: Text content of the message
          pattern: '^(?!\s*$).+'
          minLength: 1
    AgentApiMessageRequest:
      description: Contains the message to be sent to the agent
      type: object
      required:
        - application
        - message
      properties:
        userId:
          type: string
          description: Identifier of the user sending the message
        application:
          $ref: "#/components/schemas/ApplicationAgent"
        message:
          $ref: "#/components/schemas/AgentMessage"
        session:
          $ref: "#/components/schemas/SessionAgentRequest"
        parameters:
          type: object
          description: Contains parameters to configure the request to the llm.
          minProperties: 1
          additionalProperties: true
    SessionAgentRequest:
      type: object
      description: Contains the session information
      required:
        - id
      properties:
        id:
          description: Unique string that identifies the session.
          allOf:
            - $ref: "#/components/schemas/StringWithoutSpaces"
    Application:
      type: object
      description: Contains the application who is sending the message
      anyOf:
        - properties:
            id:
              description: The application identifier
              type: string
          required:
            - id
        - properties:
            name:
              description: The application name
              type: string
          required:
            - name
    ApplicationAgent:
      description: Contains the application who is sending the agent message
      allOf:
        - $ref: "#/components/schemas/Application"
        - type: object
          required:            
            - agent
          properties:
            agent:
              type: string
              description: The identifier of the agent to use for this application    
    SessionAgentResponse:
      type: object
      description: Contains the session information
      required:
        - id
        - sequence
      properties:
        id:
          description: Session identifier. Unique string that identifies the session.
          allOf:
            - $ref: "#/components/schemas/StringWithoutSpaces"
        sequence:
          type: number
          description: The sequence number message of the session    
    AgentApiMessageResponse:
      type: object
      description: Agent message response
      required:
        - message
        - session
      properties:
        message:
          $ref: "#/components/schemas/AgentMessageWithId"
        session:
          $ref: "#/components/schemas/SessionAgentResponse"
        metadata:
          type: object
          minProperties: 1
          description: Response metadata
        parameters:
          type: object
          minProperties: 1
          description: Parameters to modify the agent's behavior
    StringWithoutSpaces:
      type: string
      description: Regular expresion of string without spaces
      example: '79e2646a-a8bb-4355-b79f-42722c066155'
      pattern: '^\S+$'
      minLength: 1
